Developer Information
Source Code
The best way to get the source code for the Caiman projects is to use our Mercurial repository, which is also browseable. Obtain a local copy of the source using:
hg clone ssh://anon@hg.opensolaris.org/hg/caiman/slim_source
For instructions on how to build, please reference the README in the repository. Also, we recommend running the /opt/onbld/bin/hgsetup command from the SUNWonbld package (see below for download link) to ensure that your environment is set up correctly for OpenSolaris development.
In order to integrate code, you must do the following:
- If you are non-Sun contributor, you need to file a Sun Contributor Agreement before any changes can be accepted.
- Have a bug associated with the change. See the following section regarding bug management.
- Ensure that your change does not break the build as documented in the README mentioned above. In some cases your fix may require a modification to the README.
- Test your changes thoroughly. Make sure that they fix the problem and don't break existing functionality. If not sure that your test coverage is sufficient, consult with people on <mailto:caiman-discuss@opensolaris.org>.
- Get a code review. Use the /opt/onbld/bin/webrev tool from the SUNWonbld package, downloadable from the ON downloads page. Push the webrev to cr.opensolaris.org. Attach the list of test procedures carried out along with test results. In most cases you should ensure that <mailto:caiman-discuss@opensolaris.org> is copied on your code review discussion. During designated time periods, two reviewers are required; if in doubt, ask. More reviewers than required is always encouraged.
- You may have multiple change sets in a single integration, but use the Cadmium extension's hg recommit to remove any merge turds.
- Push the changes to the repository. New developers need to have their first several patches committed by an existing committer; granting direct repository access will then be considered. This is normally done by creating an "hg bundle" file and then sending it via email to one of the existing committers who's willing to help - for instance one of the code reviewers could handle this.
- Update the bug state as noted in the following section.
- If your integration causes a significant behavior change for either users or developers, or introduces a significant new feature, please prepare a flag day or heads-up announcement as noted in the Flag Days section.
Bug Management
Filing
Bugs should be filed on defect.opensolaris.org, under classification "Development", product "installer", "livecd", or "distro-constructor" depending on which functionality they relate to. We are also responsible for bugs filed under classification "Distribution", product "opensolaris", components "livecd" and "installer". It's a very good idea to search the database for your issue prior to filing a new one. It's entirely possible that someone has already filed the issue you are seeing. This will help alleviate the burden of marking bugs as duplicates. The following links list the bugs under each classification that we are responsible for:
Notifications
In order to be notified by email when bugs are filed or updated, you need to go to your Email Preferences tab on defect.opensolaris.org and add the following user accounts to your watch list:
qa\-distro\-constructor@defect.opensolaris.org qa\-installer@defect.opensolaris.org qa\-livecd@defect.opensolaris.org
Fixing
When you grab a bug to work on it, please assign yourself to the bug. If you decide to stop working on it, reset the assignee to the default.
Although bugzilla should constrain the state transition to some extent, if we constrain it too much, you have to go through a number of state transitions to get to where you want to go. If there are problems with the state transitions (like they're proving to be super inconvenient), raise the issue on caiman-discuss.
Generally, when you figure out why the buggy behavior is as it is, explain it and change the state to CAUSEKNOWN. When you figure out how to fix it, explain the fix and change the state to FIXUNDERSTOOD. When you actually start fixing the bug, change the state to FIXINPROGRESS. Once you've gotten all your testing done, reviews completed, etc, and pushed a changeset containing the fix to the main repository, add a comment like "Fixed in changeset XXX." (where XXX is either the short or long hex changeset id), and change the state to RESOLVED/FIXINSOURCE.
Unless you're a project leader, don't change the state to anything more resolved than that, unless you're closing it off as a duplicate, saying you won't fix it, or can't reproduce, etc. Don't mark it as RESOLVED/FIXED or CLOSED/FIXED or FIXINBUILD. These are all "gatekeeper" states, at least for now.
Flag Days
The protocol for any heads-up or flag day notifications that affect either developers or end users of the installer is:
- Create a new page on the opensolaris.org site with the details of the announcement
- Add a link to the new page created in step 1 in the main Flag Days page.
- Send an email to caiman-discuss@opensolaris.org with either a link to, or the text of, the announcement in step 1.