We need your help! This page is geared towards people interested in our code, but we'd also love if you can help with documentation, language support, and infrastructure. You are welcome to sign up on our mailing lists or drop into our chat channel on IRC. You can also find us on OpenHatch, the open source volunteer opportunity tracker.
1. Finding An Area To Contribute To
If you're not sure what you want to work on, you can start by looking at our list of bite-site bugs which should be easy for newcomers to pick up. You can also look at the entire list of issues and see if any with status "New" fit your skill set.
If you're looking for a longer-term project, we have a list of ideas for new projects for different levels skill and expertise. Alternatively you may look through the forums and mailing lists for suggestions for improvements. You may be able to find a mentor for your projects through illumos Students.
The OpenSolaris bug database also has a list of bugs for which patches are accepted. You can use the following list of bite-size bugs to find easy problems to tackle, but be sure to check if the bug in question is already fixed by checking its status, since that list was last updated in October 2009.
While the OpenSolaris bug database is no longer available, a third-party archive of the OpenSolaris bugs has a list of bite-size bugs which can help you find to find easy problems to tackle.
2. Writing The Code
Our guide to building illumos covers setting up a build environment and getting the source. You should try a build once or twice to get accustomed to the build system and source tree layout.
Since much of the code in illumos at this stage comes directly from the OpenSolaris project, you will find their Developers Reference Guide useful. In particular, the chapters Getting the ON Sources, Tour of the ON Source Tree and Making Changes in ON.
An unparalleled resource for understanding the operating system is the the book, Solaris Internals: Solaris 10 and OpenSolaris Kernel Architecture and its companion wiki, solarisinternals.com.
We have an OpenGrok source browser and search engine at src.illumos.org which is very useful for development.
We encourage you to "commit early, commit often" as you work, using your personal clone of illumos-gate.
If you are using Mercurial, there are some tools to make life easier for you and your reviewers.
hgsetup command will edit your Mercurial configuration file,
~/.hgrc, automatically to add:
- The Cadmium (cdm) extension for Mercurial.
- Some configuration for merge tools
/opt/onbld/bin/hgsetup -e <your email address> -n <your name>
If you have the OpenSolaris pkg:/developer/build/onbld installed rather than the one from an illumos build, you also want to use the '-c' flag to hgsetup to specify the cdm.py within your workspace (
-c /path/to/workspace/usr/src/tools/onbld/hgext/cdm.py). If you do use the cdm.py from your workspace, you will need to alter your ~/.hgrc whenever you delete that workspace. It is better to have an illumos /opt/onbld and to use the cdm from within it.
This notably adds the
hg recommit (reci) and
hg pbchk commands, which allow you to collapse multiple commits (provided that they haven't been pushed to another repository yet) and verify your outgoing changes are free of some common errors.
See Mercurial Workflow fore more details.
pbchk command will warn you about various stylistic problems with your code, the vast majority of which you must fix. Some exceptions are:
- For certain large bodies of 3rd party code, the C, Java, and Header style rules are waived. Ask an advocate for guidance.
- You do not have to add a copyright (or update your own copyright) if you do not wish to.
- You MUST NEVER update or alter the copyright or license text of anyone else. This is mostly obvious, but it also applies to accidentally splitting up a 3rd party copyright, or separating that 3rd party copyright from its associated license text. (If you're adding yours, add it after all the other copyright text).
3. Testing And Code Review
Before you submit a patch with the changes you have made, you should first test them. To do this, build the illumos code, and run the resulting software to verify that it works correctly.
At least one person (other than you, of course) should review your changes. You may post the changes to the developer mailing list to ask for feedback. For larger changes, please link to a resource on the web, instead of attaching a patch file. You may use a webrev (see below), a private hgweb or gitweb or online services like Bitbucket, Github, or Gitorious to share your changes. Remember to mention the issue ID in the email - if one does not yet exist, please create one!
Creating and uploading a webrev
webrev tool is an easy way to show other people changes you have made. It presents changes (including commit messages) in multiple formats viewable from a web browser. If you have installed an illumos build, you can run webrev like this:
/opt/onbld/bin/webrev -O -o illumos-123-webrev
ksh93 bldenv.sh illumos.sh -c 'webrev -O -o illumos-123-webrev'
Or to use webrev provided by installed ON build tools on a non-illumos system:
Note: The reason reason for the -I option is to provide links to our issue tracker. If you see
*** failed to import extension hgext.cdm from .../usr/src/tools/proto/root_i386-nd/opt/onbld/lib/python2.6/onbld/hgext/cdm.py: cannot import name WorkList, try running webrev from the workspace instead.
Upload the directory somewhere people can access it from the web, such as a personal web site.
We provide a convenient upload form on cr.illumos.org. To use the service, first create a zip file of your webrev:
zip -r illumos-123-webrev.zip illumos-123-webrev
Then add the file on cr.illumos.org and click "Publish".
4. Submitting A Patch
The illumos Advocates are the gatekeepers of the source repository and responsible for approving and integrating changes into the repository. After you have get positive feedback on your changes you can prepare a "request to integrate", (RTI). You'll need to include:
- The patch, or a link to the changes online (like a webrev or web repository view if you already created one).
- Some information about how the changes were tested.
- A list of people who have reviewed your code (if you're not including a commit message).
mail_msgfile from a nightly build, which should be free of warnings.
If you're using Mercurial, you can create the patch with
hg export. If you're using Git,
git show --format=\"From: %an %n%s%n%b\" -U8 (an alias is probably useful to you)
For either SCM, the commit message should be in this format:
123 Description of the issue in our tracker Reviewed by: Jack <firstname.lastname@example.org> Reviewed by: Ohana Matsumae <email@example.com>
In addition, it would make life for us easier if you include:
- The output of
hg outgoing -v(or
git whatchanged origin/master..)
- The output of
git pbchk, indicating clearly if there was no output)
When you are ready, send an email to the illumos Advocates. (You don't need to subscribe to this list, just send an email to firstname.lastname@example.org. If you're interested in what past RTIs looked like, you can browse past messages to the Advocates (Older messages )).
You should soon get a reply with additional feedback if needed, or a "thank you" for being part of the illumos developer community!