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:
git remote add me [email protected]:<USERNAME>/blender.git
git submodule sync
Alternative: GitHub Convention
It is also possible to use the common GitHub workflow, where origin
is your fork and upstream is blender/blender. For this do:
git remote add upstream [email protected]:blender/blender.git
git remote set-url origin [email protected]:<USERNAME>/blender.git
make update
origin with
upstream, and me with origin.
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, there should not be any errors when running this:
Email¶
To have the correct email associated with every commit, disable Hide
Email address in your profile settings. Otherwise for online editing and
some types of pull request merges, it may use the @noreply.localhost
domain.
The Blender repositories are mirrored to GitHub. If you like to have commits associated with your account there, add the same email address on your GitHub account. To have commits show up on your GitHub profile page, star the Blender repositories on GitHub.
Workflow¶
Create a Pull Request¶
See Git resources to learn the basics of Git, this guide assumes some familiarity.
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:
remote: Create a new pull request for 'my-feature':
remote: https://projects.blender.org/blender/blender/compare/main...username:my-feature
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.
Typically the pull request should be set to merge into the
blender:main branch.
Update a Pull Request¶
The code can be updated by simply pushing to the same branch, and the changes will be reflected in the pull request.
Adding new commits and updating to the latest changes can be done as follows. Reviewers are able to squash everything into a single commit when needed.
git checkout my-feature
git merge main # Optionally merge with main to get the latest changes
git commit file3 file4 # Add new commit
git push me my-feature
It is also possible to rewrite history with amend and rebase, which requires a force push. It is recommended to only do this before code review has started, as it is not as easy to see changes after a force push.
git checkout my-feature
git rebase main # Optionally rebase on main to get the latest changes
git commit --amend file3 file4 # Amend commit
git push -f me my-feature
Checkout a Pull Request¶
For a given pull request #123, try it out locally in a branch like
this:
git fetch origin pull/123/head:new-feature-123
git checkout new-feature-123
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.
@blender-bot build
Merge a Pull Request¶
First check carefully that the commits and files changes are as expected, and that the branch you are merging into is correct. Be careful not to merge a branch based on main into a release branch.
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 \#123being added at the end of the last commit. - Manually merged: we recommend landing through the web UI when possible. However if a pull request has been manually pushed this option can be used to close the PR and link it to the appropriate commit. The full (long) commit hash must be provided. Always mention the pull request # in the commit message.
Make sure the commit message follows the guidelines. For squashing, convert the commit message to plain text and remove images, as Gitea does not render markdown in commit messages.
Rebasing a Pull Request¶
Sometimes a PR needs to go into a different target branch. For example,
if a PR started to be worked on main but then needs to be included
in a release branch blender-vX.Y-release. You then rebase the PR
instead of creating a new one.
Go to the pull request page, click Edit next to the title, choose a
different target branch, and press Save.
The number the commits in the PR will have changed. Now you must rebase your local branch onto the new target branch, to make sure commits that do not belong in the PR are removed. Here are two way of doing it:
Rebase Onto
We will show how to change from main to blender-vX.Y-release.
Make sure you have all the latest upstream changes
Checkout the feature branch and rebase onto the target branch.
There might be conflicts, so you will have to resolve these manually.
Now carefully check the output of git log to see your branch
contains only the required changes. Test that the code still builds and
works correctly.
Finally you can push the changes. Since you have rewritten the history, you need to force push the changes.
Interactive Rebase
We will show how to change from main to blender-vX.Y-release.
Make sure the target branch is up-to-date.
Then start the rebase:
This will now show you a list of commits (it might be very long) in your configured editor. Make sure to only pick the commits that you want in your PR. Delete the lines with unrelated commits.
There might be conflicts, so you will have to resolve these manually.
Now carefully check the output of git log to see your branch
contains only the required changes. Test that the code still builds and
works correctly.
Finally you can push the changes. Since you have rewritten the history, you need to force push the changes.
Update a Contributor's Pull Request¶
Sometimes a pull requests needs a simple change before merging, like fixing formatting or rebasing to the right branch. In this case it's possible for Blender developers to update the pull request branch in the fork, if "Allow Edits by Maintainers" is enabled as it is by default.
The basic syntax is the following:
git push [email protected]:PR_AUTHOR/blender.git LOCAL_BRANCH:PR_BRANCH
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 the author considers the pull request not ready to be merged. No review is expected unless the author specifically asks for it.
- 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.
Tips¶
- To get the patch file, add
.patchto the end of the URL of the pull request. Example:
https://projects.blender.org/blender/blender/pulls/104892.patch
- Checkout a pull request into a detached head (not leaving behind a branch). Example: