# Team Processes
# General
# JIRA Workflow
##### **Jira Workflow Visualization**
[](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264323015.png)
## Planning Board
The *Planning* board will predominately be utilized by the project manager(s) and anyone involved in working with investigating / defining requirements for specific tickets. Clearly defining the scope of the work, as well as the acceptance criteria is one of the foremost responsibilities of the management team - combined with investigating what contributing factors might influence the completion of the task(s) *prior* to beginning any work ensures that stakeholder expectations are met and the chances of surprises midway through the process are reduced. A well established pipeline for tickets ensures that developers receive their work in a consistent format with all of the necessary information to execute their responsibilities and that the management team can convey realistic estimates for when the work will be completed.
##### **Planning Workflow Visualization**
[](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264357939.png)
- **Requested**
- This is where any tickets that have not been begun being scoped (defined / documented). These are high-level ideas or thoughts that will often be captured by brief explanations or a BLUFs (Bottom-Line-Up-Front). There is typically not enough information here to begin any sort of development work.
- **Scoping**
- This is where any tickets that have been Requested are further flushed out by either the project manager or individual team members. Tickets cannot progress beyond this state until their requirements have been clearly documented.
- **Backlog**
- This is where tickets that have been fully defined are placed until they are ready to be added to a particular developer’s workflow. These tickets are assigned to developers and have all of the necessary information documented, including the objective, mock-ups, and acceptance criteria.
- **Scheduled**
- This is where tickets that have fully defined are placed when they are intended for a developer to begin working on them either as part of an Epic or Sprint.
- These will need to be assessed each week in order to maintain relevancy by either promoting new tickets into this list or demoting certain tickets that are no longer in the immediate pipeline. The goal of this is to act as a “To-Do” list for developers
## Developer Board
The *Developer* board is utilized by all team members who are currently working on completing assigned task(s). This provides insight into what is currently being worked on by the team as a whole and more specifically individual team members - through consistent ticket stewardship the vast majority of ambiguity and uncertainty is removed from the development process while also increasing team cohesion. Should re-prioritization of workload priorities arise, developers can easily bookmark their existing progress and segue to whatever task that the stakeholders determine to have higher priority.
##### **Developer Workflow Visualization**
[](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264404678.png)
- **Scheduled**
- This is where tickets that have fully defined are placed when they are intended for a developer to begin working on them either as part of an Epic or Sprint.
- These will need to be assessed each week in order to maintain relevancy by either promoting new tickets into this list or demoting certain tickets that are no longer in the immediate pipeline. The goal of this is to act as a “To-Do” list for developers
- **In-Progress**
- This is exclusively for things that are actively being worked on. It is up to the developer to determine how granular they want to treat this list in terms of real-time updates, however, this should be utilized to keep track of what is currently being worked on. Multiple tickets can be included in this list simultaneously if they are related. Tickets can be moved to Started as many times as-necessary.
- **Started**
- This is where tickets should be moved if progress has been initiated, however, priorities have changed or you need a break to work on something else. The goal of this list is so that the In-Progress list can remain uncluttered and accurately represent what is currently being worked on.
- **PR Created**
- This is where tickets should be moved when code is ready to be promoted to the DEV server for testing, a PR should be initiated prior to moving the ticket as this will act as one of the “to-do” lists for the RTE. Moving forward, it is intended that developers will be creating their own pull requests, however, that will not begin until the corresponding documentation has been completed.
- **QA-Fail**
- At any point in the testing process if a ticket fails, it will immediately be dumped into this list with an explanation by the individual performing the QA tasks. That explanation will include which environment that is failed in and elaboration as to what specifically failed during testing. This will act as a “to-do” list for the developers so that they can investigate the source of the failure and make any necessary fixes prior to beginning the QA cycle again.
## QA/RTE Board
The *QA/RTE* board will be utilized by the RTE and QA team or anyone interested as to what the current status of one of their tickets might be. By isolating the testing and deployment of tickets to their own board, the management team can better understand where bottlenecks might be occurring or provide updates to the stakeholders as to what the status of a certain ticket is.
##### **RTE/QA Workflow Visualization**
[](https://wiki.bartrack.beer/uploads/images/gallery/2022-04/image-1649264438856.png)
- **PR Created**
- This is where tickets should be moved when code is ready to be promoted to the DEV server for testing, a PR should be initiated prior to moving the ticket as this will act as one of the “to-do” lists for the RTE. Moving forward, it is intended that developers will be creating their own pull requests, however, that will not begin until the corresponding documentation has been completed.
- **QA-DEV**
- This is where tickets will be moved when the RTE has deployed the code to the DEV server for testing. This will act as one of the “to-do” lists for anyone performing QA tasks. Anything in this list represents tickets that are awaiting testing.
- **QA-DEV-Pass**
- This is where tickets will be moved when anyone performing QA tasks has determined that a particular ticket successfully passes the defined criteria. The individual performing QA will make a comment on the ticket stating that it has successfully passed testing the DEV environment and is ready for promotion to the next environment, prior to advancing the ticket. This will act as one of the “to-do” lists for the RTE.
- **QA-STAGING**
- This is where tickets will be moved when the RTE has deployed the code to the STAGING server for testing. This will act as one of the “to-do” lists for anyone performing QA tasks. Anything in this list represents tickets that are awaiting testing.
- **QA-STAGING-Pass**
- This is where tickets will be moved when anyone performing QA tasks has determined that a particular ticket successfully passes the defined criteria. The individual performing QA will make a comment on the ticket stating that it has successfully passed testing the STAGING environment and is ready for promotion to the next environment, prior to advancing the ticket. This will act as one of the “to-do” lists for the RTE.
- **QA-PROD**
- This is where tickets will be moved when the RTE has deployed the code to the PROD server for testing. This will act as one of the “to-do” lists for anyone performing QA tasks. Anything in this list represents tickets that are awaiting testing. Ideally, the developer should be performing the final testing in PROD to ensure that the ticket is correctly functioning as- intended and that the original objective has been met.
- **QA-FAIL**
- At any point in the testing process if a ticket fails, it will immediately be dumped into this list with an explanation by the individual performing the QA tasks. That explanation will include which environment that is failed in and elaboration as to what specifically failed during testing. This will act as a “to-do” list for the developers so that they can investigate the source of the failure and make any necessary fixes prior to beginning the QA cycle again.
# General - High-Level Overview
# 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
[](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
[](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.
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`.
[](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 '' into 'dev'
```
**Description Guidelines -**
```
**Ticket(s):**
- [BAR-###](Ticket-URL) - _Title of Ticket_
**Notes:**
- There are no special instructions or dependencies for deploying these ticket(s)
```
[](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.
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.
[](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.
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.
[](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
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.
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
[](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).
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.
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`
[](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 & 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 => 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
Switched to branch 'develop'
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
Switched to branch 'develop'
Your branch is behind 'origin/develop' by 1 commit, and can be fast-forwarded.
(use "git pull" to update your local branch)
$ git pull
Updating a70fb07..ddbd6d5
Fast-forward
...
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 ` 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
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`
[](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` & 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 => 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
Switched to branch 'master'
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
Switched to branch 'master'
Your branch is behind 'origin/master' by 1 commit, and can be fast-forwarded.
(use "git pull" to update your local branch)
$ git pull
Updating a70fb07..ddbd6d5
Fast-forward
...
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 ` 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
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.
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.
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 & Traditional Merge Comparison
[](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
# Best Practices
# DB Migrations