Submitting a Patch
From PostgreSQL Wiki
Contents |
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.
Design your interface first
Ask yourself these questions:
- Will the user interact with this new feature? if so, how?
- What is the syntax? Have ideas, and the ability to defend technical decisions you believe strongly in.
- What are the exact semantics/behaviors?
- Are there any backward compatibility issues?
- Get community buy-in at this level of detail before you start coding. But not necessarily consensus.
- Write an opening paragraph to your email to the -hackers list that answers these questions:
- This is the kind of problem I'm trying to solve
- This is what it is doing right now
- This is what it will do.
Mostly, get someone from the community involved in your ideas as early as possible so that you can even get half-baked ideas vetted early, rather than creating something in a vacuum. Similarly, it's easier to make progress and keep patches focused if you concentrate on the smallest portion of the idea you can execute perfectly. Resist the temptation to build a giant patch all at once, as those are much less likely to be reviewed usefully and therefore committed.
You need to pay attention to what the community work cycle is. If you're sending in a brand new idea in the beta phase, don't be surprised if no one is paying attention because they are focused on release work. Come back when the beta is done, please!
Save us the trouble of reformatting your code
Please read PostgreSQL Coding Conventions. Also, follow the style of the adjacent code!
Naming things is important, and when in doubt, ask someone else to help you with names. We tend to use camel-case or underscores: thisStyleIsOkay or this_is_okay_too.
Generally, try to blend in with the surrounding code. Do not use #ifdef's to enable your changes. Comments are for clarification not for delineating your code from the surroundings.
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:
- You post patch to pgsql-hackers
- A committer picks it up immediately and commits it.
Workflow B:
- You post a patch to pgsql-hackers
- You add a link to the wiki page of the next commit fest
- A committer picks up the patch from the wiki page, and commits it
Workflow C:
- You post a patch to pgsql-hackers
- Bruce adds the patch to the unapplied patches queue after a while
- 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
- 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.
Followup on submissions
How do you get someone to respond to you?
You've sent an email to -hackers and no one has responded. What do you do?
- Start out by reviewing a patch or responding to email on the lists. Even if it is unrelated to what you're doing.
- Start with submitting a patch that is small and uncontroversial to help them understand you, and to get you familiar with the overall process.
- People are more willing to listen and work with someone who is already contributing.
- Also, in our community -- if no one objects, then there is implicit approval. Within reason!
Participating in community is a process, not a single event.
Submitting patch updates
When submitting a new version of a previously submitted patch, you should do a few additional things:
- Uniquely identify the new version, usually done via an incremented suffix on the name of the patch
- Make sure it's easy to find any earlier discussion of the patch. Don't expect that everyone will still be able to find previous submissions on their own. Either fully duplicate the information about the patch from your original messages, or provide a clear link to the earlier message via the archives. Note that you can link to your earlier post using the e-mail message ID of what you sent earlier, perhaps by checking your sent e-mail for it. That type of link is preferred because links to the archive by message number might sometimes get renumbered. See Template:MessageLink for more details.
