Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

  • Tooling around git give this line a special role. The title can be at most one line. Do not break it across multiple lines. Separate it from the next paragraph with an empty line, otherwise other tools will become confused.

  • Prefix your commit subject line with the affected package, if one can easily be chosen. For example, the subject line of a commit mostly affecting the server package might read: "server: use net.Pipe instead of TCP HTTP/gRPC connections". Commits which affect many packages as a result of a shared dependency change should probably begin their subjects with the name of the shared dependency. Finally, some commits may need to affect many packages in a way which does not point to a specific package; those commits may begin with "*:" or "all:" to indicate their reach.

    • Since the title is prefixed with a package name, don't capitalize the title. In English, the text that follows a colon (:) is not capitalized.

  • Do not end the title with a period. It's a title, not a sentence.

  • Not every commit requires both a title and a body. Sometimes a single line is fine, especially when the change is so simple that no further context is necessary. For example:

    Code Block
     docs: fixed typo in introduction to user guide
    

    Nothing more need be said; if the reader wonders what the typo was, she can simply take a look at the change itself.

    • Note however that at least one of the commits in a PR should include a release note annotation in a commit body, if only to state "Release note: none" to declare there are no user-facing changes. See Release notes

  • Make the commit title short. Other projects have a guideline of trying to keep it around 50 characters. Keeping subject lines short ensures that they are readable in git log --pretty=oneline, and forces the author to think for a moment about the most concise way to explain what's going on.

    Tip: If you’re having a hard time summarizing, you might be committing too many changes at once. Strive for atomic commits.

...

  • Place the references to bugs or github issues after the explanation, but before the release note. For example:

    Code Block
    This is the commit title
    
    Here's some explanation.
    
    Fixes #123.
    
    Release note (general change): the release note.
    
  • Ensure there is a release note: See Release notes

How others do it