Git commit messages should follow a standard convention
Introduction
Commits should be in the following format:
JIRA code (uppercase): brief description of the revision in the present tense.
Commits should have a detailed, yet brief, message about the changes.
The following are examples of good commit messages:
- Changes the header navigation order
- Adds paragraphs module
- Tweaks the search api’s html preprocessor
- Theme adjustments to the Homepage Hero
The following are examples of bad commit messages:
NOTE: Where possible, please try to make small, atomic, commits as opposed to one large commit with illogical groupings of work.
Decision
Commits should follow the below example:
PROJ-123: My atomic commit message in present tense
Where PROJ is the project abbreviation code and 123 is the ticket number from Jira.
Context
To ensure an orderly commit history, make it easy to match commits with their entry in our project management tools, and ease complex revision management operations; it is important that all commits begin with the issue code from JIRA.
This method creates a clean commit log where development can be traced, and makes referencing previous work easier if it needs completed on another project. It results in more consistent, professional histories should a project need to be handed off to another developer or agency.
Uppercase vs Lowercase was discussed at length. Uppercase matches Jira, while Pantheon branches have to be lowercase. Ultimately uppercase was decided as the standard since that matches Jira and that’s the point of the number.
The colon was added because sometimes devs would forget to add the space and it made searching very difficult. It is also a good breakpoint if commits need to be imported to a spreadsheet.
Consequences
- Development progress can be more easily traced.
- Previous work will be easier to reference if it needs to be completed on another project.
- Finding specific code will be easier and faster for all team members.
- Gives a professional impression to our work.
Exceptions
- Don’t go through amending commit messages to fix the standard, as it could break git history and have git conflicts.
- Projects that have been using lowercase until this ADR should continue with their conventions.
Additional Resources
None