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 firstname.lastname@example.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 email@example.com
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:
git format-patch HEAD~1
#git diff HEAD~1 > filename.patch will also work
Verify that it applies cleanly against the clean version of the next branch:
git checkout origin/next
git checkout -b test-next-branch
git am filename.patch
git branch -D test-next-branch
Verify that OpenMAMA compiles:
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 firstname.lastname@example.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
"[PATCH": constant prefix
$version: OpenMAMA version against which this patch was generated
$n/$total: when a change encompasses more than one patch, $n indicates the order of this patch in the series, and $total indicates the total number of patches in the series.
$subsystem: area of the project to which this patch applies.
one-line summary: summarizes the change this patch makes. This summary is copied directly into the git changelog, so make sure that your summary is descriptive. Ensure that $subsystem uniquely identifies the subsystem or driver being modified. "update to latest CVS" or "fix bug in probe" is not specific enough about what portion of the code is being modified.
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]".
[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
Patches must be reviewable in a standard Linux email client. This means in particular, no compression and no base64 encoding. It is preferred that the generated patch file is attached that its contents are also pasted at the bottom of the email body.
Patch must be apply-able by a script that has no knowledge of [MIME] encoding. You must make sure your mailer does not escape standard US-ASCII characters, wrap long lines, or encode plaintext patches in base64 (or any other encoding).
Patch must be rooted one level above a standard OpenMAMA source tree. i.e.
--- 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:
Use "reply-all" by default, except in special circumstances.
If a conversation does happen in private, never make it public without the consent of the other party.
Please don't change the subject line, as it breaks threading.
Please disable HTML email formatting.
Avoid mail clients that convert the original message to an attachment when replying.
Avoid "top posting," which means responding at the top of the email. Rather, place your comments immediately after the text you are responding to, so it is immediately apparent what you mean.
When responding to a multi-point email, please respond inline.
Never delete the body of a message when replying, unless...
If a message body is getting very long with many replies, it is appropriate to trim previous replies with the word "[snip]" - this indicates you have deleted something.
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.
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.