Branching ​

Our methodology is mostly inspired by git-flow which basically allows separating works by branch types: feature/bug/chore (user story types) and release type.

Formatting ​

Use lowercase and kebab-case for branches names.

Naming ​

Find a balance between conciseness and descriptiveness for branch titles.

All Branches Gitflow ​

Default Branches ​

• By default, there must be 2 branches: main and develop. Both branches must be created when setting up the code repository.
• The main branch is the version in production.
• The develop branch is the version currently in the staging environment.
• No one should commit directly to either the main or develop branches.
• Avoid committing history rewrites on either the main or develop branch at all costs as it could leave the project in a dire state.

Working Branches ​

• Unless in very specific cases, all feature, bug, and chore branches are preferred to be checked out locally from develop. By avoiding branching more than one node away from the main branch, we can easily avoid complex conflicts and rebasing which can take hours or days to solve.
• The definition of what constitutes a feature, bug, or chore depends on the user story types. No code should be committed if there is not a user story for the tasks at hand.
• Once merged, feature, bug, and chore branches should be deleted to keep only the default and active branches.

Releases Branches ​

• Release branches must be checked out locally from the develop branch.
• Release branches are required when opening a pull request to merge code to the main branch. Working branches are not allowed to be merged directly into the main branch.
• The name for release branches must contain the corresponding semantic version number.

Hotfix Branches ​

Hotfix branches must be checked out locally from the main branch (or the current release branch). This is the only type of branch that is allowed to fork directly off of the main branch.

• As soon as the fix is completed, it has to be merged into the main branch (or the current release branch), and the main branch needs to be tagged with an updated version number (e.g. update from 1.0.1 to 1.0.2).
• Once the fix is applied on the main branch, the fix can be merged back to the develop branch by opening a pull request from the latest main branch.

Branches Dependencies ​

During the development process, there are plenty of occasions that developers need to get some or all the changes from under-reviewing or working branches for a completely new branch. Here is the guide for handling some common situations that arise from this requirement.

Get specific commits from an existing branch ​

• Make sure the existing branch has its individual commits functional and buildable before getting them. There can be situations where the entire branch can be built successfully and the branch implementation is functional as expected, but its individual commit isn’t implemented properly. For example, a commit A contains a build fail issue (i.e. layout linking problems, a small typo, etc.) and it is fixed in subsequent commit B but only commit A is needed in the new branch.
• Coordinate with the owner of the existing branch about ensuring proper commits if you are not the author.
• Create the new branch from the develop branch.
• Apply the cherry-pick command for the commits from the existing branch that need to be included in the new branch.

This is an example of getting a single commit B from an existing branch that is still under review for a new branch. If more individual commits are needed, simply repeat the cherry-pick command per each commit. In case the needed commits are in a sequence, cherry-picking a chain of commits is also feasible with a single command (e.g. when we want to get both A and B, simply run git cherry-pick A^..B).

Get all changes from an existing branch ​

• Make sure the existing branch is functional and runnable before getting all changes.
• Coordinate with the owner of the existing branch about its readiness if you are not the author.
• Create the new branch from the top commit of the existing branch (chain the new branch).
• Working on the new branch and performing frequent checks on the existing branch for new updates.
• Perform rebasing on top of the existing branch if it introduces new changes. This is an example for getting all commits from an existing branch that is still under review for a new branch. Pull requests on source control platforms can automatically update the base branch of the new branch if the existing branch is merged at a later time.

Get changes from multiple existing branches ​

First and foremost, consider merging some of these existing branches into develop before working on your next branch. Working with teammates to review and merge the dependent code is often the most effective and efficient way to move forward in such a situation. In some rare cases, this will not be possible (e.g. external blockers), only then shall the below recommendations be considered.