Developer Information

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 developer/build/onbld package to ensure that your environment is set up correctly for OpenSolaris development.

In order to integrate code, you must do the following:

1. If you are a non-Oracle contributor, you need to file an Oracle Contributor Agreement before any changes can be accepted.
2. Have a bug associated with the change.  See the following section regarding bug management.
3. 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.
4. Test your changes thoroughly. Make sure that they fix the problem and don't break existing functionality - run all relevant unit tests to ensure no regressions are introduced. As part of any code changes, unit tests must be supplied meeting the guidelines as defined below in the section "Unit Testing". If not sure that your test coverage is sufficient, consult with people on <caiman-discuss@opensolaris.org>.
5. Get a code review.  Use the /opt/onbld/bin/webrev tool from the developer/build/onbld package.  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 <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.
6. You may have multiple change sets in a single integration, but use the Cadmium extension's hg recommit to remove any merge turds.  Note that changeset comments are expected to be in the "ON normal form", i.e.:
   <bug id> <bug summary>
7. 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.
8. Update the bug state as noted in the following section.
9. 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.

Unit Testing

All integrations into the slim_source gate are required to include unit tests. For new projects, the unit tests must demonstrate 80% coverage* of the new code. For bug fixes, the tests should at minimum cover the scenario which caused the bug. Including additional unit tests that cover additional scenarios of the modified functions is strongly preferred when modifying existing code that does not yet have 80% coverage. For Python code, PyUnit (the unittest module) should be used for writing the tests. For other code, guidelines are not yet finalized (and most non-Python code is excluded from this requirement, see below). Note that for C code that compiles into a Python module, the Python interfaces exposed should be testable via PyUnit.

Doctest may be used to supplement PyUnit tests; though please focus on primary usage scenarios for doctests to avoid cluttering the docstring of a function with edge cases.

Bug fixes to existing non-Python code are currently excluded from this requirement. Additionally, some Python code will be replaced as part of future project work; such Python code will not require tests either (tests should be delivered with the project). However, writing a few short unit tests against that Python code will not hurt in the short term. See the exclusion list** for a list of what directories and files are excluded from the testing requirement.

Existing unit tests can be run by cd'ing into their directory and running "python <testfilename>". See the lib/liberrsvc_pymod/test directory for a current example. New test suites should follow that example. In the near future, running of unit tests is expected to be integrated into a makefile target. Additionally, recommendations and instructions on checking the current code coverage percentage will be forthcoming.

* Why 80%? Is this a strict requirement?

• An 80% target is a reasonable target for unit test coverage. Getting beyond 80% generally has diminishing returns, but having coverage under 50% generally reduces the capability of the test suites to catch regressions. It's not a hard and fast requirement - code won't be rejected if it only has 79% or even 75% (however, the tests should demonstrate coverage of both common and edge cases). In other words, 80% is not as important as covering the right 80%.
• Another answer to the "why 80%?" question.

~** This list is a guideline and subject to change. If in doubt, check with <caiman-discuss@opensolaris.org> to verify the testing requirements for code changes - and do so as early as possible!

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:

Caiman development bugs 

Indiana Caiman bugs

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:

1. Create a new page on the project's opensolaris.org site with the details of the announcement
2. Add a link to the new page created in step 1 in the main Flag Days page.
3. Send email to caiman-discuss@opensolaris.org and nv-users@sun.com with either a link to, or the text of, the announcement in step 1.  These should be sent as separate emails in order to avoid internal/external cross-posting problems.
4. If your notice impacts end users of the Caiman technology, it likely needs to go into the release notes for the build that includes it so that users have another chance to be aware of it.  Contact the OpenSolaris tech lead to ensure that he can consider including it in the release notes.

What's the difference between a heads-up and a flag day?  A flag day results when it's necessary for developers or users to synchronize additional changes with yours, such as requiring a specific build level for the build to work, a new version of a build tool or compiler, or something like that.  A heads-up is more appropriate for noting changes in behavior of the build or product that might otherwise be surprising, or to note the introduction of a new feature.  If in doubt, ask one of the project leads for an opinion.

Other Information

Python Files

When adding new Python files to slim_source, please include a "shebang" line as the first line in the file. This is required in order for pkgdepend(1) to properly identify the file as being Python (pkgdepend(1) is used during a build to automatically generate the IPS dependencies for built packages). The line should be as follows:

• Executable python script: #!/usr/bin/python2.6
• Non-executable python module (only intended for import): #!/usr/bin/python