Committing Code

Hero image for Committing Code


  • 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.

    [<User Story ID>] Remove unused dependencies: Ruby and JavaScript
    [<User Story ID>] Remove unused Ruby and JavaScript dependencies
  • No limit to the length of maximum allowed characters, as commit messages should be as detailed as possible for a better understanding.

Message Structure

  • 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:

    1. Traceability of each commit which is very useful when rebasing, cherry-picking and merging.
    2. 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 wip at the end of the commit message.

    [<User Story ID>] Commit message wip

Best Practices

  • 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 Resolve feedback, Fix all comments or 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.