Submitting a Patch

From PostgreSQL Wiki

Initial patch design

If you have a trivial patch that serves an obvious need, you may be able to write the patch and submit it directly to the pgsql-hackers mailing list without having its design reviewed first. But in general, a non-trivial change should be discussed (potentially before the code is even written) on the pgsql-hackers list before being submitted as a patch.

For general coding style guidelines, see the Developer FAQ and the PostgreSQL Coding Conventions.

Patch submission

Once you believe your patch is complete, you can submit it via e-mail to the pgsql-hackers mailing list. At that time, or after you wait for initial feedback, you should also add it to the page for the next CommitFest. If your patch is large (more than 32K) you should consider compressing it with gzip before attaching it to your message, as large attachments can cause your e-mail to not make it to the mailing list. You may also submit it in-line with the message, if you prefer and the patch is small.

Context diff patches are preferred, so use cvs diff -c.

Please note that PostgreSQL is licensed under a BSD license. By posting a patch to the public PostgreSQL mailing lists, you are giving the PostgreSQL Global Development Group the non-revocable right to distribute your patch under the BSD license.

Please include all of the following information with each patch submitted

• Project name.
• Uniquely identifiable file name, so we can tell difference between your v1 and v24.
• What the patch does in a short paragraph.
• Whether the patch is for discussion or for application.
• Which CVS branch the patch is against (ordinarily this will be HEAD). For more on branches in PostgreSQL, see CVS Branch Management.
• Whether it compiles and tests successfully, so we know nothing obvious is broken.
• Whether it contains any platform-specific items and if so, has it been tested on other platforms.
• Confirm that the patch includes regression tests to check the new feature actually works as described.
• Include some docs on how to use the new feature, including examples.
• Describe the effect your patch has on performance, if any. If the patch is intended to improve performance, it's a good idea to include some reproducible tests to demonstrate the improvement.
• Try to include a few lines about why you chose to do things particular ways, rather than let your reviewer guess what was happening. This can be done as code comments, but it might also be an additional reviewers' guide, or additions to a README file in one of the code directories.
• If your patch addresses a Todo item, please give the name of the Todo item in your email. This is so that the reviewers will know that the item needs to be marked as done if your patch is applied.

The objective of all of these suggested items is to ensure that the reviewer's time is not wasted. You spent time writing the code, but that does not mean you can demand time, energy and interest from a reviewer. Make it easy on yourself and others so that your patch is accepted quickly, easily and with good humour on all sides.

Submitting the patch is just the first step towards getting it committed. Very few patches are committed exactly as originally submitted, even those submitted by experienced professional developers. For any non-trivial patch you should plan for at least 3 versions before final acceptance.

The easiest way to get your patch rejected is to make lots of unrelated changes, like reformatting lines, correcting comments you felt were poorly worded etc. Each patch should have the minimum set of changes required to fulfill the single stated objective.

Patch review and commit

There's basically three different workflows a patch can follow after it's been submitted that lead to it being commited:

Workflow A:

1. You post patch to pgsql-hackers
2. A committer picks it up immediately and commits it.

Workflow B:

1. You post a patch to pgsql-hackers
2. You add a link to the wiki page of the next commit fest
3. A committer picks up the patch from the wiki page, and commits it

Workflow C:

1. You post a patch to pgsql-hackers
2. Bruce adds the patch to the unapplied patches queue after a while
3. At the beginning of the next commit fest, Alvaro (with the help from others, I hope) goes through the patches queue, and puts a link to the wiki page of the next commit fest
4. A committer picks up the patch from the wiki page, and commits it

At any of these stages, your patch might instead be rejected for technical, style, or other reasons. These rejections will normally come with feedback on whether an improved version of that patch would be more acceptable. In those cases, you should consider updating your patch based on that feedback and re-submit.