Collaboration Best Practices#

This section outlines some of the best practices when working with Distributed Version Control Systems (DVCS). These best practices will help you get the most out Git and Mercurial when working with others.

Test Locally#

As most test suites are also included in the repository, it is good practice to ensure your changes are passing locally before opening a pull request and having the CI server run the tests for you. The two main benefits here are:

  • Not clogging up the test machine with untested and thus more likely to fail test runs.

  • Only opening pull requests that are passing locally increases the quality of feedback at the peer review stage as reviewers can focus on high quality feedback.

Agree on Workflow#

When working with others, one of the first things to agree upon is a workflow. This agreement means that everyone knows what is happening at a particular stage of the collaboration cycle and that they can deliver in accordance with the expectations.

Keep Commits To One Task#

When committing it is good practice to keep each commit to a specific task. This allows the repository admin to easily cherry pick or graft work between branches should there be a need to do so for particular release processes. It also makes it easy for colleagues to understand the changes going into a repository.

Use Descriptive Commit Messages#

When writing commit messages, it is good practice to contextualise the message by prepending a label which will give the reader a clue about what area the changes apply to, and to then write a brief but descriptive message that explains in more detail.

o  10739:0fdd6cd2b97a [default] - public
|  2 days ago by Johannes Bornhold | B:,T:
|  ac-tests: Change to be only locator based

Master Your Tools#

The best way to get good at something it to break it and fix it. One advantage of DVCS is how cheap forking and branching is. One tip is to create your own fork and master branching, rebasing, cherry picking, merging, or any other skill you currently find challenging. Once you have mastered it on the disposable branch or fork you can carry out tasks on your main repositories with confidence.