WARNING: This is the _old_ Lustre wiki, and it is in the process of being retired. The information found here is all likely to be out of date. Please search the new wiki for more up to date information.

Difference between revisions of "Submitting Patches"

From Obsolete Lustre Wiki
Jump to navigationJump to search
 
(34 intermediate revisions by 6 users not shown)
Line 1: Line 1:
When you are ready to have your patch reviewed and committed, please do so using Bugzilla by following the process described below.
+
<small>''(Updated: Dec 2009)''</small>
 +
 
 +
'''''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 [mailto:lustre-devel@lists.lustre.org 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 ===
 
=== Submitting Patches for Review ===
  
To have your changes accepted into a main-line Lustre branch, your code must be reviewed and approved. Following these steps will speed up review of your changes and increase the likelihood of success:
+
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 [[Media:Oracle_Contributor_Agreement_Nov_2010.pdf|Contributor Agreement]]. We cannot accept your contributions without this form. See [[Contribution_Policy|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.
  
1. Read, complete, and return the form found at [http://wiki.lustre.org/images/c/cd/Sun_Contributor_Agreement_1_5.pdf Contributor Agreement] We cannot accept your contributions without this form. See [[Contribution_Policy|Contribution Policy]] for more information.
+
The easiest command for generating a patch is:
 +
<pre>
 +
[lustre]$ git diff {basebranch} > {patchname}.diff
 +
</pre>
 +
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'':
 +
<pre>
 +
[lustre]$ git format-patch {since}
 +
e.g.
 +
[lustre]$ git format-patch -2      # format the last 2 commits
 +
</pre>
  
2. Generate a patch with the "-upN" flags set to diff or cvs diff.  Please do not send other kinds of patches unless your reviewer requests them.
+
If you are unfamiliar with this process, use ''git diff''.
  
'''''[[Would this step be clearer if it said something like this?]]'''''
+
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:
 +
<pre>
 +
b=<bugno> <One-line summary of change>
  
[[Generate a patch file showing the differences between your code and the code in the repository by entering:]]
+
<Full description of change>
  
[[$ cvs diff -upN FILENAME]]  '''''[[(please fix if not correct)]]'''''
+
i=<inspector1>
 +
i=<inspector2>
 +
</pre>
  
[[Where N designates the number of lines of context to include.]]
+
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.
[[Please do not send other kinds of patches unless your reviewer requests them.]]
 
  
3. Find or file a bug corresponding to your contribution at http://bugzilla.lustre.org/ . For more information about Bugzilla, see the [https://bugzilla.lustre.org/page.cgi?id=bug-writing.html Bugzilla - Bug Writing Guidelines] or the [https://bugzilla.lustre.org/docs/html/using.html Bugzilla User Guide].
+
4. Find or file a bug corresponding to your contribution in [http://bugzilla.lustre.org/ Bugzilla]. For more information about Bugzilla, see the [[Developers Guide to Bugzilla for Lustre|Developers Guide to Bugzilla]], the [https://bugzilla.lustre.org/page.cgi?id=bug-writing.html Bugzilla - Bug Writing Guidelines], or the [https://bugzilla.lustre.org/docs/html/using.html Bugzilla User Guide].
  
 
* Provide the patch as an Attachment (click on "Add an Attachment")
 
* Provide the patch as an Attachment (click on "Add an Attachment")
 
* Select the "patch" box.
 
* Select the "patch" box.
* Edit the new attachment. Under "Flags" [[select "Review" -]] '''''[[is this correct?-I don't see this entry in Bugzilla]]''''' and set the flag to a question mark (?).
+
** 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 (not a new bug), set the Inspection tag to "?" and take the owner of the bug (Assigned to field) - copy and past into field next to "?" the email address of the engineer who owns the bug.
+
** 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 submitting new bug with patch attached following normal bug submission procedure. Support team will assign bug as appropriate.  
+
** 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.
* (Still OK) Enter the email address of the person who should review. If you have not been collaborating with someone and don't know who should review your work, send an email to [mailto:lustre-rmg-team@sun.com lustre-rmg-team@sun.com]
+
** 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 update.
+
* Click on "commit" to submit the attachment and inspection request.
  
4. One or more reviewers will submit comments regarding your patch. Iterate the patch until you receive approval or the bug is closed.
+
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.
  
5. Once you have approval, commit the patch (or, if you do not have CVS access, the internal engineer assigned to the bug will direct the bug appropriately or land the change). Include the bug number and reviewer in the commit message, along with a concise description of the change.
+
6. Request patch landing permission by setting the "landing_''release'' ?" flag for your patch.
  
'''Note:''' This process applies even if you have write access to the CVS tree. If you do not follow these steps, then expect your changes to be backed out of the tree without warning.
+
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 [mailto:lustre-gate-2x@sun.com lustre-gate-2x] for Lustre 2.x, or [mailto:lustre-gate-18@sun.com 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.

Latest revision as of 10:29, 20 January 2011

(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.