# Code Management



# How To: Pull Requests

## About Pull Requests

**Pull Requests (PRs)** let you tell others about changes you've pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add follow-up commits before your changes are merged into the base branch.

- After initializing a pull request, you'll see a review page that shows a high-level overview of the changes between your branch (the compare branch) and the repository's base branch - you can also add a summary of the proposed changes, review the changes made by commits, and resolve any possible conflicts.
- Once you've created a pull request, you can push commits from your topic branch to add them to your existing pull request. These commits will appear in chronological order within your pull request and the changes will be visible in the "Files changed" tab. Other contributors can review your proposed changes, add review comments, contribute to the pull request discussion, and even add commits to the pull request.

## Creating a Pull Request

When you have completed work on a task in your local sandbox environment and are ready to begin the process of code review, testing, and deployment you will need to create a Pull Request. The primary reason for creating Pull Requests is so that the base branch only contains approved work and the RTE maintains control and full knowledge of what is in the Deployment Pipeline.

Prior to creating a Pull Request, please be sure to perform the following:

- Name the branch accordingly to the team’s convention
- Rebase `master` onto your feature branch
- Verify that the changed code only contains what is relevant to addressing the referenced ticket(s)
- Make sure objects, structures, and variables have semantic names
- Go through the changed code looking for typos, TODOs, commented LOCs, debugging pieces of code, trailing whitespaces, etc.

1. On GitHub, navigate to the main page of the repository where you would like to create a Pull Request. By default you'll be on the `<> Code` page - in order to create a Pull Request, you will need to navigate to the `Pull Requests` page  
      
    [![image-1649264660647.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649264660647.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264660647.png)
2. Once you are on the `Pull Requests` page, on the far right side of the page there will be a button that says **New Pull Request** - click this to begin the process of creating a pull request  
      
    [![image-1649264673504.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649264673504.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264673504.png)
3. The initial screen that pops up after clicking **New Pull Request** button will be a summary page where you can specify the branches involved in your Pull Request and visualize a high-level overview of the changes. Use the `base branch` dropdown menu to select the branch you'd like to merge your changes into, then use the `compare branch` drop-down menu to choose the feature branch you made your changes in. Once you are ready to proceed, click `Create Pull Request` button and continue to the next step.  
      
    <p class="callout info">By default, pull requests are based on the parent repository's default branch (which should always be `master`). If the default parent repository isn't correct, you can change both the parent repository and the branch with the drop-down lists. As a developer, the base branch for your Pull Requests should always be set to `dev`.</p>
    
      
    [![image-1649264721338.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649264721338.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264721338.png)
4. The last screen prior to the actual creation of the Pull Request is the `Open a pull request` screen - this is where you will be able to verify the branches involved, specify a title, and create a description. It is extremely important that you adhere to the team's standard convention so that the ticket can be expeditiously processed through the Deployment Pipeline. Once everything has been configured in accordance with the guidelines outlined below, please proceed with clicking the `Create pull request` button.  
      
    **Title Guidelines -**
    
    ```
    Merge '<name_of_branch>' into 'dev'
    ```
    
    **Description Guidelines -**
    
    ```
    **Ticket(s):**<br></br><br></br>- [BAR-###](Ticket-URL) - _Title of Ticket_<br></br><br></br>**Notes:**<br></br><br></br>- There are no special instructions or dependencies for deploying these ticket(s)
    ```
    
    [![image-1649264781265.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649264781265.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264781265.png)
5. Finally, after clicking the button on the previous screen you will have successfully created a Pull Request.  
      
    <p class="callout info">If there are no conflicts between your feature branch and the base branch, you should be presented with the message `This branch has no conflicts with the base branch` - if that is the case, proceed to Step #7. Otherwise, please proceed to Step #6 to determine what to do in the case of a conflict.</p>
    
      
    [![image-1649264813286.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649264813286.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264813286.png)
6. If you see a message stating `This branch has conflicts that must be resolved`, don't worry - this is perfectly normal. Merge conflicts happen when you are attempting to merge branches that have competing commits, and Git needs your help to decide which changes to incorporate in the final merge.  
      
    <p class="callout danger">Rather than proceeding with clicking the `Resolve conflicts` button, please reach out directly to the RTE to discuss a strategy for merging your feature branch into the base branch.</p>
    
      
    [![image-1649264857063.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649264857063.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264857063.png)
7. The final step, regardless of whether you have a merge conflict or not, is to advance the ticket(s) in the [Jira Workflow](https://wiki.bartrack.beer/books/team-processes/page/jira-workflow "JIRA Workflow") to the `PR Created` state. This will indicate to the RTE that you have successfully created a Pull Request and that the code is ready to be deployed and tested.

# How To: Branching

## About Branches

**Branches** are used to isolate development work without affecting the other branches in the repository - allowing you to safely develop features, fix bugs, or experiment with new ideas. At the core, this development model is greatly inspired by existing models out there and the central repository holds two main branches with an infinite lifetime: `master` and `develop`

Each repository has one default branch, `develop`, which represents the main branch where the source code of HEAD reflects the state of the latest delivered development changes queued for the next release. Parallel to this branch is `master`, which is the main branch where the source code of HEAD *always* reflects the code that is either currently deployed in production or is in a production-ready state.

Next to the main branches, our development model uses a variety of supporting branches to aid parallel development between team members, ease tracking of features, prepare for production releases and to assist in quickly fixing live production problems. Unlike the main branches, these branches always have a limited life time, since they will be removed after their purposes has been fulfilled.

The different types of branches we may use are:

- Feature branches
- Hotfix branches
- Release branches

<p class="callout info">Each of these branches have a specific purpose and are bound to strict rules as to which branches may be their originating branch and which branches must be their merge targets. By no means are these branches “special” from a technical perspective - the branch types are categorized by how we use them.</p>

The model that I’m going to present here is essentially no more than a set of procedures that every team member has to follow in order to come to a managed software development process. The goal with this model is to align our development with our defined Jira workflow and to ensure a cohesive relationship between developers within our organization. Every branch has a very specific purpose and by using the right tool for the job and adhering to the guidance outlined in this documentation we should very rarely encounter issues/conflicts related to branching and merging. By performing routine synchronizations and branching from the correct origins we ensure that the codebases that we're working on incorporate all of the latest changes and paves the way for a smooth deployment.

##### GitFlow High-Level Model

[![image-1649265054378.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649265054378.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649265054378.png)

##   


## Feature Branches

**Feature branches** are used to develop features, fix bugs, or experiment with new ideas. When starting development of a feature, the target release in which this feature will be incorporated may well be unknown at that point. The essence of a feature branch is that it exists as long as the feature is in development, but will eventually be merged back into `develop` (to definitely add the new feature to the upcoming release) or discarded (in case of a disappointing experiment).

<p class="callout info">For most work, you should branch from `develop`, however, under certain circumstances you may branch from `master` - please reference the ticket details or consult with the RTE prior to deviating from the standard operating procedure though.</p>

Prior to beginning any work on a feature branch, the ticket you are referencing must be fully documented in accordance with our guidelines in order to ensure that the scope and acceptance criteria has been clearly defined.

**May Branch From:** `develop`

**Must Merge Into:** `develop`

**Branch Naming Convention:**

- `BAR-####/brief-ticket-description`
    - `BAR-123/universal-digital-menu`

[![image-1649265176184.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649265176184.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649265176184.png)

### Process Overview  


1. Review ticket contents and verify scope / acceptance criteria has been defined
2. Checkout origin branch &amp; perform a `git pull` to ensure you are up-to-date
3. Create a feature branch in accordance with our naming convention
4. Work on feature =&gt; add commits

- At the end of each day you should perform a `git push` to check-in your progress to the remote repository
- At the beginning of each day you should merge the origin branch into your feature branch to ensure you're in sync with the target environment

5. Once you believe development is complete, perform QA to ensure your work meets the requirements
6. When development of feature has been finished, [Create a Pull Request](https://wiki.bartrack.beer/books/team-processes/page/how-to-pull-requests "How To: Pull Requests")
7. RTE reviews the Pull Request and deploys the feature branch to `DEV` to begin the formal QA pipeline

###   


### Creating a Feature Branch -

Under most circumstances and unless otherwise specified, when starting work on a new feature you should branch from `develop`. Prior to actually creating your feature branch, the very first step that should be performed is checking out your local `develop` branch and ensuring that it is up to date with the origin. If your branch is not behind the origin, you should see something similar to the following output -

```shell
$ git checkout develop<br></br>Switched to branch 'develop'<br></br>Your branch is up to date with 'origin/develop'.
```

Otherwise, if your branch is behind the origin you will need to fast-forward the latest changes which can be done by executing the `git pull` command. Once that command has been executed, you should see something similar to the following output -

```shell
$ git checkout develop<br></br>Switched to branch 'develop'<br></br>Your branch is behind 'origin/develop' by 1 commit, and can be fast-forwarded.<br></br>  (use "git pull" to update your local branch)<br></br><br></br>$ git pull<br></br>Updating a70fb07..ddbd6d5<br></br>Fast-forward<br></br>...<br></br>9 files changed, 427 insertions(+), 6 deletions(-)
```

Finally, once you have ensured that you are working on a clean, up-to-date origin branch, you are ready to create your feature which can be done by executing the `git checkout -b <branchName>` command. It is important to remember to adhere to the aforementioned branch naming convention so that we avoid any confusion throughout the deployment pipeline. Once that command has been executed, you should see something similar to the following output -

```shell
$ git checkout -b story/BAR-123/system-status-bar<br></br>Switched to a new branch "story/BAR-123/system-status-bar"
```

## Hotfix Branches

**Hotfix branches** are very much like release branches in that they are also meant to prepare for a new production release, albeit unplanned. They arise from the necessity to act immediately upon an undesired state of a live production version. When a critical bug in production must be resolved immediately, a `hotfix` branch may be branched from the `master` branch.

The essence is that work of team members on the `develop` branch can continue uninterrupted, while another person is preparing a quick fix for the production environment. The reason that we branch from `master` is because in most cases, the `develop` branch is unstable and not yet production-ready, whereas by definition the `master` branch should *always* reflects the code that is either currently deployed in production or is in a production-ready state.

When the development of a hotfix is finished, the branch needs to be merged into `master`, but also needs to be merged back into `develop` and any release branches, in order to safeguard that the bugfix is included in the next release as well.

**May Branch From:** `master`

**Must Merge Into:** `develop` and `master`

**Branch Naming Convention:**

- `BAR-####/brief-ticket-description`
    - `BAR-123/universal-digital-menu`

[![image-1649265339004.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649265339004.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649265339004.png)

### Process Overview  


1. Review ticket contents and verify scope / acceptance criteria has been defined
2. Checkout `master` &amp; perform a `git pull` to ensure you are up-to-date
3. Create a hotfix branch in accordance with our naming convention
4. Work on hotfix =&gt; add commits
5. Once you believe development is complete, perform QA to ensure your work meets the requirements
6. When development of feature has been finished, [Create a Pull Request](https://github.com/BarTrack-Beer/process-documentation/wiki/How-To:-Pull-Requests)
7. RTE reviews the Pull Request and deploys the hotfix branch to `master` to begin the formal QA pipeline

###   


### Creating a Hotfix Branch  


Under all circumstances, for development of a hotfix you should branch from `master`. Prior to actually creating your hotfix branch, the very first step that should be performed is checking out your local `master` branch and ensuring that it is up to date with the origin. If your branch is not behind the origin, you should see something similar to the following output -

```shell
$ git checkout master<br></br>Switched to branch 'master'<br></br>Your branch is up to date with 'origin/master'.
```

Otherwise, if your branch is behind the origin you will need to fast-forward the latest changes which can be done by executing the `git pull` command. Once that command has been executed, you should see something similar to the following output -

```shell
$ git checkout master<br></br>Switched to branch 'master'<br></br>Your branch is behind 'origin/master' by 1 commit, and can be fast-forwarded.<br></br>  (use "git pull" to update your local branch)<br></br><br></br>$ git pull<br></br>Updating a70fb07..ddbd6d5<br></br>Fast-forward<br></br>...<br></br>9 files changed, 427 insertions(+), 6 deletions(-)
```

Finally, once you have ensured that you are working on a clean, up-to-date origin branch, you are ready to create your feature which can be done by executing the `git checkout -b <branchName>` command. It is important to remember to adhere to the aforementioned branch naming convention so that we avoid any confusion throughout the deployment pipeline. Once that command has been executed, you should see something similar to the following output -

```shell
$ git checkout -b hotfix/BAR-123/missing-dependency<br></br>Switched to a new branch "hotfix/BAR-123/missing-dependency"
```

## Pull Request Submitted, Next Steps  


In terms of lifecycle of a branch, we need to be extremely mindful of the current status of our Pull Requests - if you neglect to stay vigilant on the state of a PR and continue to develop on a branch that has already been deployed, you are all but guaranteed to encounter conflicts when you attempt to merge your code.

Briefly summarizing why this occurs, it is simply due to how we are handling [pull request merges](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/about-pull-request-merges) - since we utilize the **Squash+Merge** approach, this means that during the merge we are effectively creating a new commit object that consolidates all of the commits within a particular branch into a single commit on the target branch.

<p class="callout info">You can merge pull requests by retaining all the commits in a feature branch, squashing all commits into a single commit, or by rebasing individual commits from the head branch onto the base branch.</p>

The reason that we've chosen this approach is because it drastically improves the readability of our commit logs on `develop` and `master`, while also avoiding losing any referential information about the historical existence of a feature branch by grouping together all commits that together contributed to the feature.

##### Squash+Merge &amp; Traditional Merge Comparison

[![image-1649265498940.png](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/scaled-1680-/image-1649265498940.png)](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649265498940.png)

When visually comparing the differences between the **Squash+Merge** and **Traditional Merge** approaches, you can see that the former is much more concise and promotes readability whereas in the latter case, it is impossible to see from the Git history which commit objects together constitute the implementation of a feature. In addition to being unable to decipher contribution towards a feature, reverting a whole feature (i.e. a group of commits), is an absolute nightmare in the latter situation, whereas it is easily done in the Squash+Merge approach.

Now you might be asking yourself, "well okay, that seems logical enough - how does that relate to my development?" - the answer is quite simple but requires you to be proactive in order to mitigate significant headache (for yourself and the RTE). If a Pull Request is still in the `OPEN` state, that means you may continue to check-in code to your feature branch on the remote repository - this will automatically update the reference branch in the Pull Request. However, if a Pull Request is marked as `MERGED` that means the branch you were originally working on is *dead* - any continuation of work on that branch will likely result conflicts in the future when we try merging the code.

> Merge conflicts occur when you merge branches that have competing commits, and Git needs your help to decide which changes to incorporate in the final merge.

The reason that these conflicts occur is partly due to the merging strategy that we've chosen - since all of your commits are compressed into a single commit when they are merged, any future Pull Requests will attempt to re-introduce the same (or altered) code that has already been merged via commits that don't actually exist, which is how we end up with conflicts. For more information about conflicts, please reference the documentation [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/about-merge-conflicts).

- - - - - -

It is recommended to cease further development on any feature branches once a Pull Request has been created. That is not to say that you cannot continue work on a particular feature, you simply need to adjust *where* you are performing that work --or-- communicate with the RTE and get their input on how to tackle the situation.

The best advice that I can recommend is the following:

- Communicate with the RTE when you are performing additional work on an existing branch with an `OPEN` Pull Request
- Following an `OPEN` Pull Request, create a new ticket/branch to discretely capture the additional work that needs to be performed on a particular feature
- Following a `MERGED` Pull Request, create a new branch from the origin with an identical naming convention to perform additional work