Commit Messages

The first line of a git commit message should be a short summary of changes and should be 50 characters or less. You should keep it concise, but clear. If your change is related to a ticket, you should include a ticket id or reference at the beginning of the message, so it is visible when viewing a list of commits.

If you feel that the commit needs a longer explanation, leave a blank line after the first line and then organise the rest of the message into paragraphs (or bullet point lists), wrapped at 72 characters. Imagine the first line as the subject of the commit while the rest of it as the message. It is a good idea to configure your git message editor to automatically format commit messages for you and warn you when you are breaking the format.

When writing commit messages, you should use the imperative and present tense. This matches the format of the commit messages that git automatically generates.

Example commit message:

MB-49: Add git standards

Include commit message standards based on popular git commit message
guidelines and branching standards based on our workflow.

For more information and explanations of the reasons behind these standards, you can read this article.

Branches

We use Vincent Driessen’s Git branching model in our workflow. The model specifies several different types of branches:

• Main branch

  We use master as our main branch. This is the branch that is deployed to production environments. Code should only be merged into the master branch as part of a production deployment, once it has been finished, reviewed, tested internally and externally, and approved for release.

  While we typically deploy from HEAD of master, we should always make sure that the version that is being deployed is tagged. See the ‘Release branches’ and ‘Tags’ section.

• Next release branch

  Our next release branch is develop. Code is merged into this branch after a code review. Our staging environments usually contain the code from the develop branch.

• Feature branches

  We use feature branches for our normal day to day work and consider every change we make to be a feature itself or a part of a feature. Ideally, all code changes should be committed on feature branches. Since all of our work is tied to tickets in our project management system, we usually create a feature branch for each ticket we work on. Feature branches are created from develop and merged back into develop after a code review. In rare cases, it is convenient to create a feature branch from develop and then create individual ticket branches from that in order to split up a big chunk of work into smaller ones for easy code reviews. If a feature branch is being merged in manually, you should use --no-ff to force git to keep a record of the feature being merged in. The naming convention for feature branches is the ticket reference followed by a short dash separated description of the feature, e.g. MB-49-git-standards.

• Release branches

  Release branches are temporary branches that we use during production deployments. These branches are created from develop and merged into master. It is critical to use --no-ff when merging a release branch in order to keep a log of when a release has been merged in. Our naming convention for release branches is release/<version>. For Magento sites, we use the date of the release as the version in the yyyy.mm.dd format. Finally, if making more than one release on the same day, append a -n to the release version, for example release/2014.02.13-2.

• Hotfix branches

  We only use hotfix branches when working on critical problems that are found on production environments. A pull request should still be created and reviewed before being deployed. Hotfix branches are created from master and merged back into master. The naming scheme is similar to the approach used for feature branches except that the branch name is prepended by hotfix/, e.g. hotfix/MB-11-incorrect-colour.

  Once the hotfix is complete, please make sure that you also create a new tag for a release before deploying. This is so we can always be sure what code has been deployed to the site as it’s not obvious when looking through tags if MB-11-incorrect-colour is a previous release or not. Without this it would be hard to know what to rollback to.

In practice, we use git-flow to manage the branching model.

Tags

When finishing a hotfix or a release, git flow will automatically create a tag. Once named it will also ask for a tag message. We recommend this message to be a list of tickets and summaries of changes between the last tag and now, e.g.

MB-123: Summary of the issue
MB-124: Summary of the issue
MB-125: Summary of the issue
MB-126: Summary of the issue

If you’re tagging a release manually, then please do so in the same way as you would have when creating a release branch, i.e. yyyy.mm.dd. If making more than one release on the same day, append a -n to the release version, for example release/2014.02.13-2.