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.
We use Vincent Driessen’s Git branching model in our workflow. The model specifies several different types of branches:
masteras our main branch. This is the branch that is deployed to production environments. Code should only be merged into the
masterbranch 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
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
developand merged back into
developafter a code review. In rare cases, it is convenient to create a feature branch from
developand 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-ffto 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.
Release branches are temporary branches that we use during production deployments. These branches are created from
developand merged into
master. It is critical to use
--no-ffwhen 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.ddformat. Finally, if making more than one release on the same day, append a
-nto the release version, for example
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
masterand merged back into
master. The naming scheme is similar to the approach used for feature branches except that the branch name is prepended by
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-colouris 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.
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