All source is stored within the Talis GitHub.
Our culture around source code is one of Shared (or Collective) Code Ownership1, this means that we are all, as a team, collectively responsible for our code. We all own the code and in principle any one of us can make changes anywhere2.
Working with branches
master is always regarded as deployable, following a green build.
For any changes, always create a branch. The branching model we use is based on GitHub Flow3. We branch from
master, implement our changes on the branch and then merge the branch back down to
Committing often is also a good practice. Every committed revision gives you a rollback position, and makes it easier for you step back through changes locally4.
Before merging a branch, always raise a pull request, and make sure your changes have been reviewed by others.
If you have commited often during the lifetime of your branch, you may have many commit messages. While these are great for providing rollback positions during development, they can litter the log of the master branch. Having single commit messages for each story helps with release tracking. Consider squashing your branch to a single commit, after your code has been reviewed.
Once your branch is merged into master, delete the branch.
Squashing takes the smaller commits made during development into one single commit, ready to be merged into master.
The example below shows a branch, STORY-002-Modify-Squash-Example, with four commits made during the development of the story.
To squash the four commits into one, use the git rebase command. Rebase the branch onto the master branch you are merging into with the following command:
Running the rebase command opens an editor which lists all your commits:
In the editor, leave the first commit unchanged, but change the following commits from “pick” to “squash” or just “s” as shown below.
Save and exit the file.
You now need to write the commit log message for the single commit being created by the squash. An editor is opened which displays the log messages for each of the squashed commits.
You can edit this to create a new commit message. Anything that is commented out will not be in the final commit message. Save and exit the file.
The git log now has only one commit:
Your now ready to push your branch back upto github. However, a normal push will be rejected because your local branch and the remote branch have diverged. Perform a force push with the –force option to push the squashed branch.
While working on a branch, commits provide rollback positions and commit messages reflect this. When merging, the commit message becomes part of the master branch’s commit log.
The content of the commit message at that point can help with things like release tracking and linking or even automatically closing GitHub issues.
For example, using the git command:
shows the commits between tags v1.0.0 and v1.1.0 i.e what is in the release v1.1.0. This can be used to update release notes and the status of stories. It is the single point of truth of what is contained in a release.
The following keywords will also close a GitHub issue automatically when the branch is merged to master.
It is therefore very important that we write good commit messages5, following these simple guidelines:
The wrapping of text at 50 characters for the Summary line and 72 characters for the body is very important, and is explained here6.
The tools we use can also be configured to help us adhere to this, for example, if you use
Vim for editing your commit messages you can configure it to wrap text correctly by enabling the indent plugin in your