Source Control

Bitbucket hosts all code. The backend and frontend repos have three main branches – development, staging, and master – that correlate with the three different deployed environments as summarized in the following table:

You may notice a discrepency between the ENV var and actual environment name. There is some refactoring work (infrastructure, code, etc) that needs to happen at some point. But just be aware that when you see qa in logs or lambdas, it doesn't necessarily mean the qa environment.

The goal is for Production to always be stable and QA to almost always be stable.

Jira contains all tasks along with notes and who they're assigned to. A link is created between task and code by including the CP-1234 designation at the beginning of a branch name or as part of a commit message, preferably both.

Task Branching

At TitanHouse we follow a pretty standard form of feature-based (branch-based) development. Ideally, each Jira ticket would correspond to a distinct branch. (In the event that it is easier to group several tickets into one branch, make sure to include the ticket number somewhere in the commit or comment.)

Overview

(developer = you, qa-tester = Anna)

1. Developer creates a new branch, for example CP-1111, based off staging.
2. After code is completed, developer publishes CP-1111 to bitbucket.
3. Developer opens a pull request (PR) for CP-1111 into development and tags peers for review.
4. After at least one peer approves developer's code, developer merges it.
5. Developer opens a PR for CP-1111 into staging and tags QA-Tester.
6. QA-Tester merges/deploys code into staging when ready to test.
7. If feature passes qa, QA-Tester manually deletes the branch, moves the ticket to the 'Ready for Production' column, and adds to the deployment sheet.
8. If feature does not pass qa, QA-Tester reverts the PR for CP-1111 and moves the ticket back to the 'ToDo' column.
9. Developer reverts QA-Tester's revert in CP-1111, applying to staging(?).
10. Developer fixes issue and begins again at Step 2.

Create New Branch

Using your git tool of choice (or the bitbucket web interface), create a new branch. Make sure to name the beginning of the branch the same as the Jira ticket.

🎫 Move ticket into the "In progress (Dev)" column

Publish Branch and PR

Get your git code up to the bitbucket repo and PR into development. It is possible at this point that you will have conflicts. If the conflicts are due to changes that are in development but not yet in staging do not resolve them. Rather, make a comment that the PR is ready for review.

🎫 Move ticket into the "Done (Dev)" column

Merge to Development

After receiving at least one peer review, press the Merge button from the PR on bitbucket. However, if there are conflicts and you are unable to merge, do the following.

1. Checkout development branch locally
2. Merge feature branch (CP-1111) into development
3. Resolve conflicts
4. Push the resolved changes into origin/development

Bitbucket will recognize this as a merge and automatically flag the PR as having been merged. The advantage of resolving conflicts this way is that you can use the same branch to PR into development, staging, and potentially master.

At this point your code is in the development branch, but may not be deployed yet. Check the bitbucket pipeline list and deploy, if necessary.

Open a new PR from the feature branch into staging and tag Anna. The reason for tagging the QA-Tester is to make it easier to identify which PR is the correct one to deploy. It is possible that a large Jira ticket may have multiple PRs open at the same time and to minimize the chance for mistake, tagging helps.

🎫 Move ticket into the "Ready for QA" column

QA Process

Up until now, the developer has been responsible for merging code into the staging branch. This now falls under the QA-Tester's responsibilities. The end result should be that staging will be more stable which means that new features branched off of staging are more likely to be stable.

When the QA-Tester is ready to test a feature, s/he will merge and deploy it into the QA environment.

🎫 Move ticket into the "In QA" column

Fail QA

From the PR into staging, the QA-Tester presses the 'Revert' button. This will also trigger a pipeline. If the QA-Tester is immediately putting another ticket into QA, it is not required to deploy the pipeline as this will happen with the following merge pipeline.

Pass QA

QA-Tester will manually delete the branch (so as to minimize branch-creep in the git repo) unless the ticket is labeled as fast-track-to-prod. Once these 'hotfix' tickets have passed QA, notify Tan/Troy immediately.

🎫 Move ticket into the "Ready for Production" column

Add the ticket to the 'Next' tab of the Deployment sheet.

Fixing a Feature that Fails QA

The trade-off for keeping the QA/staging environment clean is that continuing development in the original branch requires an extra step. The "correct" way to undo a revert is explained here, however a quicker way is to revert the revert. To do this, find the PR where Anna reverted your branch from staging and choose the option to 'Revert' it. This will open up a PR dialog. For the target branch, choose your original feature branch (CP-1111) and optionally rename the resultant PR. Merge this PR and pull the latest code into your local environment.

This double revert should not change any code of yours locally, but it modifies the git history so that when you fix whatever things need fixing, all of the relevant code is present. Continue the process above with Pushing a Branch and opening a new PR.

In Summary

A feature begins with the current state of QA. Then it goes to DEV, followed by QA, followed by PROD. The push into DEV happens as soon as the developer finishes. The push into QA happens when the QA-Tester is ready to test. The push into production happens roughly every 2 weeks (unless it is something that must be hotfixed asap).