- Anything in master is in a deployable state at all times.
- To work on something new, create a new branch off of the head of master and give it a descriptive name.
- Commit to that named branch locally and regularly send your work to the same-named branch on the server.
- Branches should be short-lived and frequently integrated with master.
- When you need feedback or help, or you think the branch is ready for merging back into master, open a pull request (PR).
- After someone else has reviewed and approved the code in the branch, it can be merged into master and the branch removed.
- Once your changes are merged and pushed to master, it can be deployed.
There is only one branch that has any specific and consistent meaning, and that is master. The master branch is always stable and tested. This branch is rarely (if ever) rewound – any issues will be resolved by either reverting commits or adding new commits that fix the issue.
Code is considered deployable when it builds successfully, a versioned artifact is created, all the automated tests pass, and – as applicable – it starts up without errors. It does not necessarily mean that it is ready for production.
When beginning work on a feature or fix, create a descriptively named branch off of the stable master branch. It can be useful (but it is not required) to include the Jira ticket number in the branch name. This makes it easy to see what everyone is working on.
Since the only branch that needs to be deployable is master, we can and should push our code changes frequently to the same-named branches on the server. This doesn’t mess anyone up or confuse anything because anything that isn’t on master is just something we are working on. It also ensures that our work is always backed up in case of laptop loss or hard disk failure, as well as letting everyone see where we are in the process of implementing the change.
Branches should be short lived and regularly integrated with master. Smaller batch sizes reduce risk. This will greatly reduce the number and severity of merge conflicts. Long lived branches can quickly become stale and diverge too far from the current state of the repository, reducing or eliminating any perceived value.
Opening a pull request (PR) can mean that you are ready for a code review; but it can also mean that you would like some feedback on your work, have questions or need assistance before proceeding. It is recommended for these latter options to prefix the name of PR with [WIP]for Work In Progress.
Opening a PR is a request to start a conversation about your work. PRs can easily be closed without merging, so the level of commitment is low.
By default, branches can only be merged into master after they have been peer reviewed by other developers on the team. Code changes should include adding or updating unit and integration tests, and all automated tests should be passing prior to merging.
Ideally, as soon as changes are merged, they are deployed. But even if it isn’t deployed right away, new code can now be branched off of the changes, and future changes based on your work can be deployed.