Dev:Doc/New Committer Info

For All Developers

You've been added as bf-blender project member with Git write access, welcome! You can use this access now to work on Blender. You're also welcome to work on other features or fixes as discussed with the team online. Please always verify before committing with the module owners in wiki, or with one of the bf-blender admins: Campbell Barton, Brecht van Lommel, or with Ton Roosendaal. You can also consult the bf-committers email list or talk with us in IRC if in doubt.

Here's the standard checklist & guidelines all new devs need to read:

- The main rules for committing are:

1. Always ensure that what you commit is either on your "own code", or you've verified the patch with the owner of the module. If you want to change things in other parts of the code, check with one of the developers who owns/maintains that.
   
   
2. Always carefully check which files you have included in your local Git commit before pushing it to the main repository. Use 'git status', 'git show' and similar commands to inspect your commit. Check carefully if the files marked as modified are actually what you want to commit. Also ensure that you pull in changes recent changes to ensure your changes are still working.
   If needed, use 'git rebase --interactive' to reorder, edit, fixup (join) or split the not yet pushed commits so they keep a comprehensible history and also to avoid commits that break 'git bisect' or other tools like automatic builds.
   
   
3. Verify that the licensing and copyright information is correct in (especially the new) files you commit.
   
   
4. Always contribute code in the style as used in the code you've worked on. We just have a long history of software development, and can't restyle all code to a unified standard. Keeping style per file consistent at least keeps things readable.
   Make sure you use real TABs (not spaces), and don't configure your editor to cleanup whitespace.
   For new code see our Code Style Guide
   
   
5. Blender is strictly cross-platform, and we only accept code that compiles for all current platforms correctly. for OpenGL (nothing newer than 2.1, or correctly wrapped), Python (3.5), gcc (4.2 should work), msvc (2013 should work), etc. If in doubt, send a patch to the bf-committers list.
   
   
6. if you think your commit may cause errors on others configurations, note this in your commit log, or better: notify the bf-committers mailing list or go to the irc.freenode.net #blendercoders channel.
   
   
7. Subscribe to both mailing lists below Before committing:
   http://lists.blender.org/mailman/listinfo/bf-committers/
   http://lists.blender.org/mailman/listinfo/bf-blender-cvs/
   
   
8. Blender has stages in development cycles called BCon levels, even if your patch is acceptable we may be about to release so check on the current BCon stage. (Release Cycle Docs)

- Blender Foundation -

Best Practice

Etiquette

• When making very large changes to blenders source, be available some time after (1-3 hrs), in case this breaks blender in some way.
• Don't make large changes before release
  See: Release Cycle Docs
• Developers may reply to your commit logs, even if you don't read every message on the bf-committers mailing list, at least be sure to reply comments on your commit.
• When committing contributions from others, include their name in the log and the patch number from the tracker where applicable.

Code Style

C/C++

There's Code Style Guidelines which should be followed when working on source code.

Some areas aren't ported to this code guidelines and when working on them, current style should be followed. Do not mix actual feature implementation / bugfix with style cleanup.

Python

For python we follow pep8 where possible.

See: Best Practice - Style Conventions

Commit (Best Practice)

• Always double check your commits before pushing
  (just to quickly see other changes aren't accidentally being included).
• Make sure you're using SSH to push, as described in Dev:Doc/Tools/Git#Commit_Access.
• Don't combine code cleanup/refactoring commits with functional changes, since it makes it harder to investigate when a commit causes new bugs.
• Avoid having trailing whitespace in the new code.
• Don't do minor cleanup to existing code (such as trailing whitespace, space between functions, fullstops ending comments... or other superficial changes).
• Store test files in: https://svn.blender.org/svnroot/bf-blender/trunk/lib/tests/

Commit Logs

Please follow 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 what exactly the problem was.
• Explain what you fixed on a user level, not just what was wrong in the code. Do explain those things too, but please do both then.
• 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 cases 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.

Category: single short line saying what the feature you 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, I like to start the commit with "Cleanup: " then.

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.

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", keep the commit message clean.

Branch Usage

Committers can create their own branches, this section notes some guidelines, avoid cryptic names or wordplay.

• Branches should be named clearly, relating to their purpose.
  good: cycles_ctests, ui-api-refactor, temp-mathutils-doc, particles_refactor
  bad: test, experiment, terrible_consequencer.
• If you intend to make a branch for some short-lived development use the prefix temp-.
  This means others know its a branch with will eventually be deleted.
  We sometimes use these to more easily collaborate on a patch before going into master.
• Even though you have a lot of freedom to make changes in your own branch, please avoid committing large binary files,
  since this increases the size of Blender's repo for everyone.
  This includes changes to the splash image, fonts... etc. Or anything which isn't essential to your development.
• If any branches you create serves no useful purpose to keep (has been rebased into master and doesn't have history worth keeping or its been abandoned entirely),
  you can delete them:
  

  git push origin --delete <branchName>