Submitting Patches

(Updated: Dec 2009)

NOTICE: A transition from CVS to Git took place on Monday, December 14. For more information about the transition, see the Git Transition Notice. For details about how to migrate to Git, see Migrating to Git.

---

When you are ready to have your patch reviewed, follow the process described below for submitting it using Bugzilla.

Note: It is sometimes desirable to solicit reviews of a patch on the lustre-devel mailing list to expose the patch to a wider audience. However, this will NOT put the patch on track to being accepted into the Lustre repository.

Submitting Patches for Review

To have your changes accepted into a mainline Lustre branch, your code must follow the Lustre Coding Guidelines, and be reviewed and approved by senior Lustre engineers. Following these steps will speed up review of your changes and increase the likelihood of success:

1. Read, complete, and return the form found at Contributor Agreement. We cannot accept your contributions without this form. See Contribution Policy for more information.

2. Testing the patch is required before it can be submitted. The patch must include any new tests specific to the bug/feature. See Testing Lustre Code for specific details.

3. Generate a patch with diff -upN, git diff, or git format-patch. Please do not send other kinds of patches unless your reviewer requests them.

The easiest command for generating a patch is:

[lustre]$ git diff {basebranch} > {patchname}.diff

where {basebranch} is the branch you are patching against (b1_6, b1_8, or master). Note this patch will include committed and uncommitted changes on your branch. If you well-defined patches with proper commit comments as described below, it is also possible to use git format-patch:

[lustre]$ git format-patch {since}
e.g.
[lustre]$ git format-patch -2      # format the last 2 commits

If you are unfamiliar with this process, use git diff.

If sending changes with git format-patch we ask that you follow our standard commit message format when making your commits, so that the patch can more easily be identified in the future. If you are doing a rebase, you will get a chance to modify/combine your commit messages. Commit messages for final patches should look like this:

b=<bugno> <One-line summary of change>

<Full description of change>

i=<inspector1>
i=<inspector2>

If you are not using git format-patch, then simply adding the above lines at the start of the submission email is enough. If you are making a commit prior to submitting the patch for inspection, simply omit the i=<inspector> lines, and then use git commit --amend to change the commit comment after inspection is complete.

4. Find or file a bug corresponding to your contribution in Bugzilla. For more information about Bugzilla, see the Developers Guide to Bugzilla, the Bugzilla - Bug Writing Guidelines, or the Bugzilla User Guide.

• Provide the patch as an Attachment (click on "Add an Attachment")
• Select the "patch" box.
  • If submitting a new bug with a patch attached, follow normal bug submission procedures. The support team will assign the bug and inspections as appropriate.
  • If working with an Lustre internal engineer, under "Flags" set the inspection flag to "?" and copy the email address of the engineer into the adjacent Requestee: field.
  • If you have completed testing of the patch, set the "acc-sm_passed_release +" flag for the branch(es) that passed testing. If you have not actually run the acceptance-small.sh test script to completion (unless advised otherwise) you should describe the testing performed to date, and can optionally set the "more-testing_release +" flag.
  • If you have not been collaborating with someone on the Lustre team and don't know who should review your work, assign the inspection to lustre-rmg-team@sun.com
• Click on "commit" to submit the attachment and inspection request.

5. One or more reviewers will submit comments regarding your patch. Iterate the patch until you receive inspection approval, have passed all requested testing, or the bug is closed.

6. Request patch landing permission by setting the "landing_release ?" flag for your patch.

7. Once you have landing approval (as given by the branch maintainer in the form of a "landing_release +" flag on the patch, mail the patch to lustre-gate-2x for Lustre 2.x, or lustre-gate-18 for Lustre 1.8. Include the bug number and reviewer in the commit message along with a concise description of the change, as stated above.