We are very excited to receive outside contributions -- many of our employees first became involved with Lustre® by making patches and demonstrating their expertise as outsiders.
Learning enough about Lustre to make serious changes is a fairly daunting task: Lustre solves a lot of very challenging problems, and doing so inevitably requires complexity. Unfortunately, as is the case with too much software, there is not a lot of detailed documentation about the internals of Lustre. In many places the APIs are decent and the functions self-explanatory; in many places they are not.
The Contribute section includes basic information about how to check out code, patch your kernel, build a tree, and run simple tests. If you run into difficulties you may be able to get help from the lustre-discuss mailing list.
One Legal Hurdle
Before you can contribute code to Lustre, or get write access to the CVS repository, you need to sign and return our Contributor Agreement to email@example.com. We require this step for several reasons:
- We need to make sure that you're only contributing code that you own. By certifying that you wrote the code (and that you control the rights), you take legal responsibility for your contribution.
- By agreeing to Joint Copyright, you make it easier for us to protect the project and company from license violations -- only the copyright holder is empowered to act against violations (see the FSF's comments about this topic).
- You also make it possible to continue to sell and distribute Lustre under other licenses, including non-free licenses. This business model is what pays the bills, allowing us to maintain and improve Lustre, release the code under an open source license, and participate in open development (which, generally speaking, pays few of the bills).
Because you remain a copyright holder of what you wrote, you can use the code you contributed in almost any fashion. Of course, this only applies to the software that you contribute, not software written by others.
We will gladly acknowledge your authorship in the source code -- our point is not to try to take credit for your work. If you make a substantial contribution, please update the boilerplate at the top of the source file as part of your patch.
Finally, if you write software for a living (or attend a university), there is a good chance that your organization owns all of the software that you create. In this case, you have three options:
- Get an officer or authorized representative of the organization to contribute the software.
- Get an officer or authorized representative of the organization to waive its rights to your software, so that you can contribute it yourself. In this case, please enclose a short waiver signed by the officer.
- Do not contribute the software.
You are responsible for making sure that you control the rights to the software before you contribute it -- if there is any doubt, please consult the organization or an attorney. If you ever find that you contributed software that you shouldn't have, for any reason, please notify us right away.
Making a Contribution
When you are ready to have your patch reviewed and committed, please do so via Bugzilla. Follow the process described below.
Submitting Patches for Review
To have your changes accepted into a main-line Lustre branch, you must have your code reviewed and approved. The following 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.
2. Generate a patch with the "-upN" flags to diff or cvs diff. Please do not send other kinds of patches unless your reviewer requests them.
3. Find or file a bug for your issue at http://bugzilla.lustre.org/ . For more information, review the Bugzilla user guide.
4. Attach your patch as an Attachment (not a comment):
- Provide the patch as an Attachment, and select the Patch box.
- Edit the new attachment. Under "Flags" select "Review" and the question mark.
- 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, try firstname.lastname@example.org
- Submit the attachment update.
5. One or more reviewers will submit comments regarding your patch. Iterate the patch until you receive approval or the bug is closed.
6. Once you have approval, commit the patch (or ask for it to be committed for you, if you do not have CVS access). Note the bug number and reviewer in the commit message, along with a concise description of the change.
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. We have to be strict, or the chaos becomes unbearable.
Our current policy is that anyone may create and maintain a private branch in CVS. We ask, however, that you observe the best practices outlined in this document. It will save you a lot of effort.
If you have demonstrated a history of good work by submitting several non-trivial and correct patches, you may want to have write access to the CVS tree.