Tools/Pull Requests

= Pull Requests =

This page describes the tools used for code contribution and review. The process for effective contributions is described in Contributing Code.

Code reviews are a key measure to assure changes are of a good quality. They help preventing bugs, architectural issues or potential maintenance problems. And having your code reviewed also generally keeps you on your toes.

One Time Setup
This assumes you have the Blender repository already checked out on your computer, following the build instructions.

Fork

 * Go to Blender repository and click the Fork button.
 * Confirm the fork with the default settings.
 * Now you will have to add your personal fork as a remote in your local git repository. Click SSH to see the correct URL, and then add it like this:

SSH Key
In order to push to the fork repository, you need an SSH key. If you don't already have the file ~/.ssh/id_rsa.pub, there's a simple command to generate such keys which works on Linux, macOS, and in Git Bash on Windows:

This command will generate a private key id_rsa and a public key id_rsa.pub in ~/.ssh. The private key must never be shown or sent to anyone else to avoid compromising your account, but the public key is safe to share.

The contents of ~/.ssh/id_rsa.pub can be copied and pasted into the account settings on projects.blender.org, after clicking "Add Key". Any name for the SSH key is ok.

Test
Now you can test if your SSH key and remote URL works:

Create a Pull Request
In your git local git repository, make changes in a branch:

When you are done, push this branch to your fork:

If all goes well, a message will be printed to the console with a link to create a PR:

Alternatively, you can go to the page of your fork on projects.blender.org. There you can select the branch, and click the icon next to it create a PR from the branch.



Update a Pull Request
You can update the code by simply pushing the same branch, and the changes will be reflected in the pull request.

You can also add additional commits instead of amending an existing one. Reviewers are able to squash everything into a single commit when needed. For bigger changes, splitting things up into multiple commits often makes them easier to review and test.

Checkout a Pull Request
For a given pull request `#123`, try it out locally in a branch like this:

Tests
Before merging, building and tests should pass on all platforms. Run tests locally to find issues before submitting pull requests.

Reviewers can start tests on the buildbot by including the following line in a comment to the PR. See blender-bot for details.



Merge a Pull Request
Reviewers can merge pull requests directly from projects.blender.org. There are two strategies:
 * Squash: squash everything into one commit, using the PR title and description as the default commit message. You have the opportunity to edit the commit message before the push goes through.
 * Rebase and fast-forward: push all the commits in the PR, with commit messages unchanged except `Pull Request #123` being added at the end of the last commit.

Make sure the commit message follows the guidelines.

Pushing directly to the repository is possible though not recommended. In such cases the # must be manually added in the commit message, and the pull request manually closed.

Quality Checklist
There are a number of common mistakes in contributions. This checklist can help both contributors and reviewer help verify everything is taken into account.


 * Is backward compatibility with existing .blend files and the Python API preserved?
 * Is the naming and user interface consistent with related functionality in Blender?
 * Can the feature be made easier or more efficient to use?
 * Does the change have a negative impact on performance?
 * Can a little refactoring help make the code easier to understand and maintain?
 * Does the code have comments?
 * Was clang-format used to format the code to follow the conventions?
 * Do the automated tests still pass?

Guidelines for Reviewers

 * The pull request text should be usable as the git commit message (see the guidelines for details).
 * Be explicit when some changes are to be addressed before committing, without the need for a review iteration.
 * If the pull request is not approved the author is expected to make another iteration.
 * If the change needs agreement on the design task first, put the pull request on hold by adding a "WIP: " prefix in the title, indicating it it is not ready for review and merging.
 * Developers are expected to reply to pull requests in 3 working days.
 * Add relevant modules/projects to tags.
 * Assign individuals (instead of modules/projects) for reviewers, to avoid too much noise.
 * Encourage new developers to do code review, it's a good way to learn and important to grow the project.