Git - Best practices

Since some times, I work with several developers in my team. They are all connected to a GIT repository (TFS or VSTS) and they regularly ask me when and how to create a Pull Request efficiently.

After several articles on the subject and several weeks of use, here are my conclusions.

Commit Rules

1. Commit as often as possible.
   • At least once a day
   • Please check that the code compiles correctly.
2. Commit only the source code.
   • .cs,.ts,.xaml,.html, resources, ...
   • Use the file .gitignore to help you
   • Don't commit your compilation results, Nuget or NPM packages
3. Write a clear and explicit comment.
   • To help the code review process
   • To help write Release Notes
   • To facilitate subsequent maintenance
   • Start your comment with Fix, Add or Change
   • Use short comments (maximum 80 characters)
   • Reference the associated Work Items via #

Branches

When you start to write a new feature, create a branch that follows the clear conventions:

• master contains the code corresponding to the version currently in production.
• developer contains code common to all developers.
• releases/[version] contains the codes of all deployments already performed.
• Features/[feature-name]
• Features/[feature-area]/[feature-name]
• users/[username]/[description]
• Hotfix/[description]

Examples: users/dvoituron/addhelpdocumentation, features/loginscreen, hotfix/statperformance

The 'develop' branch

This branch contains code usable for all developers. It is therefore important that its content is correct and that other developers can easily find their way around. To do this, we will merge the code being written, via the Pull Request process (see below).

As several developers regularly update this branch develop, it is interesting to be notified of an update. VSTS allows to define notifications to receive an email when a developer to modify the branch ‘develop’. In this case, it is advisable to run a rebase from ‘develop’ to your branch, to resolve possible conflicts as soon as possible (and to dispose of the latest changes).

Pull Request

Once the code is written correctly in its branch, it is time to create a Pull Request which will be checked and finally validated to be merged to the develop branch. To avoid conflict problems, it is advisable to regularly update your branch with the new codes pushed in ‘develop’ (see above).

The Pull Request process is quite simple, and is mainly done online:

1. Merge (merge or rebase) one last time the development code to your branch, to avoid conflicts.
2. Compile your code locally and run all unit tests.
3. Start the Pull Request process (via VSTS or TFS): click on the [Pull Request] button and choose to merge your branch to develop.
   • Give a specific title to the Pull Request. It corresponds to the functionality under development.
   • Describe in detail the content of the feature. This Description field and references to Work Items can be used to write Release Notes.
   • Check or specify Code Reviewers.
4. The request is pending until Reviewers check the quality of the code. If necessary, they can add comments or adapt the code and commit the Pull Request which will then be updated.
5. Once the review process has been completed, the last Reviewer (or manager) approves the Pull Request :
   • Merge into Squash mode to compress all commits into a single commit in 'develop' branch. This makes the development history much more readable.
   • Delete the feature branch, which has become useless. Work history and commits are kept in the Completed Pull Request.

Demo

A 5 minute demo is available here.