When contributing code to Blender, it first ought to be reviewed. This is mandatory when you do not have the right to commit your changes directly, but even for seasoned Blender developers it can be beneficial to have an extra pair of eyes to go over their code.
This wiki page describes the process of code contribution and patch reviews. There is a separate page that describes the tools involved.
Before Starting to Code
If you plan to work on bigger changes or new features, it's usually a good idea to Contact Developers in the area you plan to work in, and figure out if the feature is desired and how it should be designed, before spending time coding it. By talking to developers first, you can make sure that your work aligns with other plans, and that the approach is sound.
If you are contributing a small feature or fix, you can usually just go ahead, create a patch and submit it.
Submitting patches is very welcome! To make timely and proper reviews possible, we'd recommend you to check on the guidelines below.
- Format the description for your patch so it can be used as the commit message.
- Use a horizontal separator (
---) to separate non-commit-message-related text, so it's obvious what the text isn't intended to be included in the commit log.
- Follow code guidelines: no new warnings, comment your code, add documentation, follow code style of the file you are editing.
- Try to keep everything in a patch related to one topic. If there are two things you're fixing, e.g. adding a new hotkey and fixing a memory leak, submit two separate patches, one for each topic.
- Include all the Ingredients of a Patch in the patch description (see the section below).
- Patches solving bugs or compiling errors need similar information as for bug reports, on how to reproduce the issue that is solved.
- If there are bigger design question to solve, open a Patch or Design task first, so that code review can focus mostly on the implementation.
- A review has to be done both on functional level (does this fit with Blender's design or roadmap) and technical level (does the provided code conform to our coding style, match design and planning, and is sufficiently readable and maintainable). It is fine to submit a rough patch first to demonstrate the functional level, and then update the patch so that it is also functionally sound, but do make this clear in the patch description.
- Be explicit about who should maintain the new code. For larger patches it's relevant to note if you seek one of the Blender project members to maintain it, or whether you propose to get involved as team member to maintain/improve it in the future.
- Provide as much relevant documentation as possible. Images, screenshots, short video clips or .blend file examples do do wonders! Attach all of this in the tracker itself by dragging them into the description field.
- The typical reviewers with final approval should be module owners, but anyone can and is encouraged to participate.
- Make it easy for people to review the code. That means you do not submit huge patches, but break up your work into multiple smaller patches and reviews.
- Code refactoring, new features, bug fixes, etc. should be submitted as separate code reviews. You can have them as separate commits in the same local Git branch.
- Code reviewers should try to either accept, request changes, or reassign to another reviewer quickly, to unblock the developers working on their features. This makes the process more inviting to new developers and more usable for existing developers.
Ingredients of a Patch
Before adding a new feature (even a small one), it needs to be discussed and motivated. As a minimum, the patch description should include the following where applicable:
- Description of the problem that is addressed in the patch.
- Description of the proposed solution, and a motivation as to why this is the best solution.
- List of alternative solutions, and a motivation as to why these are undesirable.
- Limitations of the proposed solution.
- Mock-up of the proposed user interface and a description of how users are going to interact with the new feature.
These ingredients don’t have to be full essays. A few well-written sentences can be very illuminating as well. An example can be found in D7533. A simpler example that still adheres to the above can be found in D6352.
The order in which these are listed is also relevant, as it helps to guide the reader towards understanding what the patch is doing. To give a counter-example, starting a patch description with “This drop-down menu allows the artist to…” can be hard to understand at first, as the reader doesn’t know anything about the underlying problem yet.
Every day developers have to dive into Blender's history to find rationales on changes. When this results in a commit or patch with no rationales at all, developers end up having to make guesses and assumptions, which tend to backfire and result in bugs. The alternative is to spend a significant amount of time understanding the changes and testing corner cases. By writing down some (brief) background information and rationales for a change, it helps to make better, more informed decisions later.
Submitting the Patch
Ideally you'd first contact developers and talk about your ideas. This will already give you an idea as to who will be suitable for reviewing your code. Of course it also happens that you have an idea, start coding it, and then want to find reviewers.
Doing a good review can take a lot of time, and because many Blender developers are volunteers, we cannot make a promise you'll get such a review here! Below are tips on how to get reviews done. To get developers to review your patch, you can get in contact with them in various ways:
- Assign or CC them when submitting the patch on developer.blender.org.
- Subscribe to the bf-committers mailing list and send a mail that you added a patch.
- Go on #blender-coders on blender.chat and talk to developers.
When the patch has actual new functionality, user reviews will help a lot too. A lot of patches were tested first by providing public builds via websites like graphicall.org, or via forums like blenderartists.org.
Help, my patch got rejected!
Even for experienced developers, it is very common that reviewers do not accept a patch immediately. When you send in a patch, please expect that you'll be asked to change things around. After all, that's what reviews are for -- to find weaknesses and solve them.
We're all software developers here, and we understand code work on Blender shows a lot of commitment, and has been your time investment with all the good intentions to help us out. A rejection doesn't mean we don't like you, nor that we don't like to see actively helping out as a contributor! It's all human beings here, with personal preferences, and ideas for how to make Blender a better product.
It makes Blender as an open source project strong if we allow active developers and maintainers to make individual choices too. They're getting empowered to do development, which also implies they have get the benefit of the doubt in making tough decisions.
Nevertheless, mistakes can always happen! Here's what to do to get a patch considered after all:
- Contact the developer list with a friendly request for (additional) reviews. Make sure the current maintainer of code at least is aware of this rejection.
- If no result or consensus in the project team can be found, you can ask the admins of bf-blender to provide a final verdict.