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
- When naming other developers in a patch, use their full name instead of nickname.
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.
- Commit messages should use American English suitable for technical documentation.
- Abbreviations should only be used when they are well understood in the field.
- ASCII for diagrams and arrows can be used where appropriate.
- Use real names to refer to people, not usernames.
- 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!
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.
- 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.
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.
- Make it clear when there are no functional changes.
Cleanup: single short line describing what you cleaned up Optionally more information about the cleanup.
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 you must format the commit message to keep only these fields.
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.