Commit Organization

Every commit should be

  • atomic

    • each commit contains only one logical change

    • whitespace fixes, refactorings are separate from functional changes

  • coherent

    • tests are updated in the same commit

    • tests pass at every commit: if necessary, introduce temporary methods/code

  • have a well-written commit message

Commit Messages

A commit message should

  • give a high level overview/summary of code changes

  • make sense without seeing code diffs & external resources

  • be consistent (e.g. using American spelling), no typos

  • be correctly formatted for readability (e.g. text wrapping)

  • have a meaningful title (summary)

  • provide relevant information (for reviewers/other developers) in the description, if necessary

Commit Titles

A good commit title

  • briefly explains what the commit does: your team member has a good idea of what was done in a commit and whether or not his/her parts are affected

    • makes clear which part of code is affected

Commit Descriptions

Commit descriptions may include the following

  • Why is the change needed?

    • Fix bug: What was the problem? What caused the bug?

    • Improve performance: Why is this necessary?

    • Enhance feature: How does the enhancement make the software better?

  • How does the commit solve the issue?

    • Give a high level overview of code changes.

  • Why did you choose this approach?

    • What other approaches did you consider?

    • What are the tradeoffs?

    • What difficulties did you face? How did you overcome them? Did you try other (more obvious) approaches? If they failed, why? This may be useful for other developers, if it saves them time from trying an approach that has already been shown to fail.

  • What are the side effects?

    • Is there an impact on performance?

    • Impact on other features? e.g. This change results in a bug in another feature.

    • Does this commit break build? Do developers need to take action e.g. run migrations?

  • What are the limitations?

    • What are the known limitations?

    • What about future scope for improvement?

  • Useful references

    • Useful resources for tackling the problem

    • Past commits that are relevant

    • Refer to issues in bug tracker

  • Giving credit/acknowledgements

References