What is a patch?
A patch is no more than a plain text file which contains data about the differences between two versions of the same file or files on a line-by-line basis. If a line changes in a file it is compared to the corresponding line in the original version of the file, and the old line along with the newer version are stored in the patch file. The end result is a list of instructions for updating the code of the original file so that it matches the code in the version it is compared to. Below is an example of what you might find in a simple patch file:
Why work with patches?
Writing and applying patches can be both rewarding and very frustrating. In most cases, creating a patch is one of the only effective ways of sharing changes you've made to Blender's source code with others for review and/or feedback. Likewise, the features and code that others contribute are often only available in the form of a patch. It is thus very important to know how to create and apply patches in order to facilitate quick and accurate communication between developers regarding Blender's source code.
When should I submit a patch?
Writing patches is generally done for two reasons:
To distribute a bugfix: often you may spot a bug in Blender's source code before a developer has the opportunity to do the same work. Creating a patch is the perfect opportunity to get the work done without putting it on someone else's (likely very long) todo list.
Contributing new features: many coders take it upon themselves to add functionality to Blender in their own free time. Without these 'homebrew' projects, Blender would not be what it is today. Outside contributions from hobbyists and professionals alike are crucial to the development process. Yes that means you!
What should my code look like?
As a general rule of thumb, when creating a patch you should adhere to the style of the file you are editing.
How do I Apply Patches?
In order to apply the changes stored in a patch file to your checkout of the Blender source code you need to use the following command in your blender root directory. Note: This requires that patch is installed.
patch -p0 < mypatch.txt
You will then be given an indication of whether or not the operation was a success. If it was not, there are many possibilities as to why your source code was incompatible with the source code the patch was created against. It is best to contact the author to be sure you both have an updated version of sources or edit the resulting files manually to be sure everything is as it should be. Be warned! This can be a time consuming and frustrating process. You can immediately undo the changes made by a patch by using the -R switch as shown below, again from the root directory:
patch -p0 -R < mypatch.txt
Creating the Patch
If you do not have SVN write access, the best way to submit a patch to Blender is first to give your patch to someone else and have them test it. Once thats done, you can do various things, see the Contact page for details:
- Add the patch in the Patch Tracker.
- Subscribe to the bf-committers mailing list and send a mail that you added a patch in the tracker to email@example.com.
- Go on #blendercoders irc and talk to developers
To get a patch just type this inside the root blender directory:
svn diff > ../patch.txt
Try to keep everything in a patch related to one topic. If there are two things you're fixing, eg. adding a new hot key and fixing a memory leak, submit two separate patches, one for each topic.
Submitting patches in this tracker are very welcome! To make timely and proper reviews possible, we'd recommend you to check on the guidelines below.
- Patches solving bugs or compiling errors will usually get handled quickly. Note that for such patches we typically need similar info as for bug reports, which you can find on this page. Especially for more complex fixes we really need to be able to verify that ourselves.
- Patches providing new features are more complicated to handle. 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).
- For larger patches it's relevant to note if you seek one of the Blender project members to submit and 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, or a website which you know will remain accessible for a long while.
How to get a review
Doing a good review can take a lot of time, and because almost all regular 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:
- The most efficient way is to contact the maintainers of the code yourself. You could actually do this in advance even, to verify if your proposed work would make a good chance for inclusion. You can best find maintainers of code by reviewing svn commit history in svn. Also check on the module owners page and consider joining one of our communication channels via the Get Involved page.
- 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 on blender.org or blenderartists.org.
- To speed up the process, ensure that you:
- Follow code guidelines: no new warnings, comment your code, add documentation.
- Include a test case; either a .blend or a script that demonstrates and tests the functionality you are adding or fixing.
We recommend every one of the active Blender developers to spend some time on reviewing patches. In the past we've done that a lot, and with a bit of luck you'll get great comments and advice for how to improve it. The review may also ask you to post your patch on the Code Review website.
Help my patch got rejected!
First of all, 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.