Style Guide/Commit Messages

Commit Message Guidelines

Please observe the following guidelines and provided templates for your commits:

  • 50 characters for first line and 72 for following ones

Many git tools assume these metrics for proper rendering, such as git log --pretty=oneline or gitweb. Automated reports or just plain future development depend on good logs.

Bug Fixes

  • Don't copy the bug report name verbatim if it's not descriptive, explain exactly what the problem was.
  • Explain what you fixed on a user level, do not focus only on what was wrong in the code.
  • Start the commit log with e.g. "Fix T12345: " or "Fix:", so it's immediately clear that it's a bugfix.
  • Bonus Feature: mentioning "Fix T12345" will autoclose the bug T12345 on developer.blender.org!

Example:

Fix T12345: single short line to explain on a user level what the bug was

Optionally, more user level information about which scenarios the bug
happened in, why it was fixed in this particular way, etc.

If non-obvious, some technical note about what the cause of the bug was and
how it was solved.

Features

  • Explain what the feature does on a user level, not just the code changes.
  • Keep user level explanation and code changes explanation separate.
  • Explain features in terms of their names in the user interface, not internal code terminology.
  • If it's not obvious, explain what the feature is useful for or when it should be used.

Example:

Category: single short line saying what the feature you have implemented is

More user level information about how this feature works, explanation about why
it's good to have, link to docs or release notes, etc.
 
Optionally short technical notes about how the feature was implemented.

Code Cleanups

  • Make it clear when there are no functional changes.

Example:

Cleanup: single short line describing what you cleaned up

Optionally more information about the cleanup.

Code Review

If you are committing a patch that went through code review, the following lines should be added at the end. If you use Arcanist these are added automatically on landing, however this adds too much unnecessary information, so it's best to format the commit message to keep only these fields.

Example:

Reviewed By: someone

Differential Revision: http://developer.blender.org/D123

This will autoclose the revision and give us a standard way to indicate who reviewed the code. Please remove all other fields like "Subscribers" or "Reviewers" to keep the commit message clean.