Patch Submission

The following guidelines on patch style and the submission process are provided to help you be more effective when submitting code to the OpenMAMA project.

When development is complete, a patch should be submitted to the openmama-dev@lists.openmama.org mailing list. A review of the code will take place, and when the code is accepted it will be integrated into the next build, verified, and tested. It is then the responsibility of the developer to maintain the code throughout its lifecycle.
 
Please submit all patches in public by sending them to the openmama-dev@lists.openmama.org mailing list. Patches sent privately to subsystem maintainers will not be considered. As this is an open source project, be prepared for feedback and criticism; it happens to everyone. If asked to rework your code, be persistent and resubmit after making the changes.

Scoping a Patch

Smaller patches are generally easier to understand and test, so please submit changes in the smallest increments possible, within reason. This is because smaller patches are less likely to have unintended consequences, and if they do, getting to root cause is much easier for you and the subsystem maintainer.
 
For this reason, smaller patches have a much higher likelihood of being accepted.

Generating a Patch

When you are ready to submit a patch for inclusion in an OpenMAMA release please use the following technique for generating a patch, and verify that it applies cleanly against a pristine git pull.
 
These instructions assume your local OpenMAMA git tree is located at ~/openmama and that your changes are committed in your local git tree:
cd openmama
git format-patch HEAD~1
#git diff  HEAD~1 > filename.patch will also work
git pull
git checkout origin/next
git checkout -b test-next-branch
git am filename.patch
git branch -D test-next-branch
scons
NOTE: You can also generate patches with diff against a clean source tree; however, build generated files in the source tree might make the process difficult. Using git is much easier.

Submitting a Patch

OpenMAMA follows the best practices established by the Linux kernel development community.  All patches should be submitted as text within an email as well as attaching a generated patch file to openmama-dev@lists.openmama.org
 
If you are new to the project, please see these examples of the OpenMAMA patch format.

1. Email Subject Format

The email subject has a precise format, communicating several pieces of information.
[PATCH $version $n/$total] $subsystem: one-line summary
Keep your overall subject line under 65 characters or so.
 
The scripts will strip all the text inside the brackets ("[PATCH ...]"), and replace it "[PATCH]".

Example:

[PATCH 1.0 1/2] Message Bridge: reduce latency when disconnecting
The "$n/$total" may be omitted if there is only one patch in the series. Writing "1/1" is not necessary.

2. Email body contents: description

At the beginning of your email, use as many lines as you wish to describe the patch. This text is copied directly into the git changelog.
 
Include comments and other data (such as diffstat) you don't wish to be in the OpenMAMA changelog following a "---" terminator line. The terminator must be on a line by itself.

3. Email body contents: patch

--- a/drivers/scsi/megaraid/megaraid_mm.c 2004-08-31 04:05:10 -04:00
+++ b/drivers/scsi/megaraid/megaraid_mm.c 2004-08-31 04:05:10 -04:00
or in other words, the patch must be apply-able using
patch -sp1 < filename.patch

4. One patch per email

This cannot be stressed enough. Even when you are resending a change for the 5th time, resist the urge to attach 20 patches to a single email. If you do send multiple emails, make sure the second and subsequent emails are sent as replies to the first, to keep them all together in a thread.

5. Sign your work

The sign-off is a simple line at the end of the explanation for the patch, which certifies that you wrote it or otherwise have the right to pass it on as a open-source patch. The rules are pretty simple, and the sign-off is required for a patch to be accepted.

6. Attach patch and copy contents to email body

In order to ensure that submitted patches are applicable, it is preferred that the patch is attached to the email and also that it's contents are copied and pasted at the end of the email body. MIME (the mechanism by which files are attached to an email) has historically created a problem for patch import scripts. Some unfortunate email programs insist upon base64 encoding for all attachments, which completely shrouds the patch to some scripts and mailers. Also, depending on the email client used to send the patch, whitespace errors may be introduced into the emal body. Thus both attaching the patch as well as pasting it's contents will minimise the chances of a patch recieved being inapplicable.

7. Follow these instructions even when resending

Quite often, when a patch receives comments, the patch author will (deep in an email thread) include a revised version of their patch but omit the email subject one-line summary, and overall patch description. This isn't script friendly, and requires the patch description to be hand-edited.

Credit to Jeff Garzik for the process writeup, adapted for OpenMAMA.

Replying to a Patch

When you respond to an email about a patch, whether yours or someone else's, please use the following etiquette:

What if my Patch is Rejected?

It happens all the time, for many reasons, and not necessarily because the code is bad. Take the feedback, adapt your code, and try again. Remember, the ultimate goal is to preserve the quality of the code and maintain the focus of the project through intensive review.
 
Maintainers typically have to process a lot of submissions, and the time for any individual response is generally limited. If the reason is unclear, please ask for more information.
 
If you have a solid technical reason to disagree with feedback and you feel it has been overlooked, take the time to thoroughly explain it in your response.

Escalation

In a project of this size, patches sometimes slip through the cracks. If you submitted a patch to the openmama-dev mailing list or bugzilla and did not receive a response within 5 business days, please send an email to openmama-dev and in the first line of that email, include this phrase "Patch escalation: no response for x days". This is one of those rare cases where you should "top post", to make sure that we see the escalation text.
 
This text is the cue to the project leaders / community managers that we need to make sure someone responds.