Capitalize the first word as commit message must be read like a sentence.
[<User Story ID>] add capitalized commit messages
[<User Story ID>] Add capitalized commit messages
Start commit messages with a verb, so there is a clear expectation of what action has been taken. This must be specified in the present tense.
[<User Story ID>] Removed ... [<User Story ID>] I fixed ...
[<User Story ID>] Remove ... [<User Story ID>] Fix ...
Periods are only acceptable when commit messages span over multiple sentences.
[<User Story ID>] Remove unused dependencies.
[<User Story ID>] Remove unused dependencies. These used to break the staging server.
Colons are verbose and break the sentence principle, so don’t use them.
No limit to the length of maximum allowed characters, as commit messages should be as detailed as possible for a better understanding.
Include the user story ID between brackets
]at the beginning of each commit message:
[<User Story ID>] As a user I can view the list of job positions
When the pull request references a GitHub issue, the user story ID must be prefixed with
[#<User Story ID>] As a user I can view the list of job positions
This serves two main purposes:
- Traceability of each commit which is very useful when rebasing, cherry-picking and merging.
- Integration with our project management tool as commits will be displayed in the user story card.
Commits of incomplete features must be appended with the suffix
wipat the end of the commit message.
[<User Story ID>] Commit message wip
To not waste CI/CD resources, skip the build if it is expected to fail or be re-triggered again. To achieve that, a
[skip ci] prefix can be included in the commit message structure. For example:
[skip ci] [<User Story ID>] As a user I can view the list of job positions # or [skip ci] [#<User Story ID>] As a user I can view the list of job positions
Later on, if there is a need to start a build back, simply use the Git command - amend to remove the
[skip ci] tag from the most recent commit message.
When to skip the pipeline
When a pull request is marked as a
draftpull request. → More commits can still be introduced later on and thus triggering the builds at this point is usually unnecessary.
When a pull request’s branch is based on a branch other than the primary
developbranch. → This is more commonly seen in large teams where multiple branch implementations for the same feature depend on each other as explained here. Triggering a workflow at this point is unnecessary because more rebase actions/conflicts are introduced until the rebase happens on the latest
When a pull request has a base branch as the
developbranch, but the
developbranch is going to be updated before the pull request can be merged. → This usually happens when multiple branches are ready for review and are based on the
developbranch simultaneously. The Team Lead will normally merge pull requests with enough approvals ordered by the creation date. Triggering a workflow at this point is also unnecessary until the pull request is fully ready to be the first to get merged.
Write clear, precise and meaningful commit messages. Think that there is a high chance that you or someone else will be reading this commit message a few years from now. What would you like to communicate to your future self or developer about?
[<User Story ID>] Implement change because ... [<User Story ID>] Fix the error triggered by ... in the following situation ... [<User Story ID>] Set up the build process so that ...
Do not write commit messages like
Fix all commentsor combine all unrelated code changes in one commit when taking care of reviewer feedback. Instead, write meaningful commit messages that reflect your changes.
Stage file changes in a meaningful way i.e. commit changes for a group of files together with a good commit message. All staged files must correspond to the same change. If the commit message uses the word “and”, then this probably is a good indicator that the commit might need to be split it up into separate commits.
Commit regularly to avoid losing any massive amount of changes while working continuously on a large task.