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:

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 ragarding Blender's source code.

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!

As a general rule of thumb, when creating a patch you should adhere to the style of the file you are editing. However, its better to be safe than sorry! Before beginning work on a project with the Blender source code, it is best to read the Coding Style. This will save valuable time for all parties involved by giving you the guidelines you need to create patches that are consistent with the existing code base and will also inform you on how to maximize readability and organization.

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 two things;

1) Add the patch in the Patch Tracker.

2) Subscribe to the bf-committers mailing list and send a mail (including the patch number!) that you added a patch in the tracker to bf-committers(at)blender.org.

To get a patch just type svn diff > ../patch.txt from inside the root blender directory, then email us 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.

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 match by using the -R switch as shown below, again from the root directory:

patch -p0 -R < mypatch.txt

This generally will be enough to revert your sources to their previous state.

 

1) Submission guidelines

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 (is the provided code conform our coding style, matches 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.

2) 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 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 maintainers page and consider to join 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 www.blender.org or www.blenderartists.org.

3) The review process

We recommend every 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 advise for how to improve it. However... to prevent people to feel obliged to spend time on lengthy review discussions we also add a grading convention:

A patch review can be a simple comment only saying "+1" (I like it) or "-1" (I don't like it). No justifications are needed for that, nor a note whether this is about functionality or implementation.

Getting three "+1" marks from current bf-blender team members means that your patch gets the highest priority for review, discussed in our weekly irc meetings and assigned to one of the maintainers for a serious review. Other people's votes will only be viewed as an indication.

Getting three "-1" marks from current bf-blender team members will allow us to close the patch without further explanation.

When positive or negative marks both occur, we'll sum the total and apply the rules above.

4) 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 (Matt, Willian, Martin, Ton).