Style Guide/Commit Messages

=Commit Message Guidelines=

Please observe the following guidelines and provided templates for your commits: Many git tools assume these metrics for proper rendering, such as   or gitweb. Automated reports or just plain future development depend on good logs.
 * The first line represents the subject of the commit.
 * The body the commit messages must be separated from the subject by a blank line.
 * Lines should not exceed 72 characters.
 * When naming other developers in a patch, use their full name instead of nickname.
 * Do not embed images in the commit description

Language

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

Commit Types
Nearly all commits are one of the following 3 types, and must follow the associated conventions.

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 "Fix #12345: " or "Fix:" (for unreported bugs), so it's immediately clear that it's a bugfix.
 * Bonus Feature: mentioning "Fix #12345" will autoclose the bug #12345 on projects.blender.org!

Example: Fix #12345: 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.

New Features and Improvements

 * 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.
 * Start with a category like "Cycles:", "Sculpt:" or "UI:".

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.

Relevant bugs, design or to do issues can be auto closed or referenced with respectively `Fix #123` or `Ref #123` at the end of the commit message.

Code Cleanups and Refactoring

 * Make it clear when there are no functional changes.
 * Separate cleanup commits from functional changes. First clean up the code, commit that as a cleanup commit, then commit the functional changes.
 * Start the subject line with "Cleanup:" or "Refactor:" (for bigger changes).

Example: Cleanup: single short line describing what you cleaned up

Optionally more information about the cleanup.

No functional changes.

Code Review
For code review, the recommended workflow is to use pull requests.

Pushing directly to the repository is possible, and the pull request # must be manually added in the commit message then. The pull request will not automatically close.

Author / Committer

 * If you commit a patch of your own, you are author and committer of the commit (the default).
 * If you commit a patch on behalf of someone else, there are two cases:
 * If the full name if the original author is known, you are committer, but the original author becomes author in git. Commit as `git commit --author "Full Name "`.
 * Otherwise, you remain author and committer in git. However, you have to add `Contributed by @nick` to the commit message. The pull request # should be mentioned anyway.