OpenSolaris

1. Project: Companion - /opt/sfw: Free and Open Source software
   1. Announcements
   2. Events
   3. News
   4. Blogs
   5. Discussions
   6. Leaders
   7. Observers
   8. Contributor Guidelines
      1. Checklist
      2. BuildCCD
      3. Companion Content
   9. Downloads

Welcome to the Companion CD (CCD or /opt/sfw) consolidation. If you've reached this page, you're probably starting to think about contributing software into the Companion. Welcome! We're happy to have you!

Eligible software:

Stable, open source software is eligible for inclusion into the CCD. If the software is also contained in another Solaris consolidation, the CTeam may request you pursue update of that software rather than duplication in the CCD.

Getting started:

1. Check the current content list .
   
2. Learn how to build software in the CCD by reading the build instructions .
   
3. Locate a piece of software you'd like to contribute or update.
4. Take a look at the Contribution Process for a preview into what happens after you've got the code working.
5. Read the Contribution Guidelines below for requirements, suggestions, and hints about the technical process of incorporating software in the build process.
6. If you're updating a piece of software,
   1. Replace the source tarball with the updated version
   2. To get things building, you'll need to update Makefile.sfw and install-sfw to point to the latest versions. You may need to also modify configure and compile options, or remove old patches applied.
   3. Take a look at the other files at the root of the software's compilation directory. Most of those will need to be updated too. e.g. DIST*.sfw and README.*.
   4. Check for new excecutables, docs, libraries, etc. added by the new version, and include them in the appropriate package definitions in usr/src/pkgdefs.
   5. If code changes are required, try to commit those to the main distribution location (upstream location) of the software's source rather than diverging the source here. Help make the lives of those who want to download and compile from the main trunk of the software better!
7. If you're contributing a new piece of software,
   1. Look at the Contribution Process again, and get the legal process started before embarking on a task that might be thwarted by lawyers.
   2. Get the software compiling on Solaris, and take notes about the steps you took.
   3. Look at some existing examples in the gate to determine how to translate your notes into Makefiles, DISTfiles, and READMEs in accordance with the Contribution Guidelines.
8. If you're running into problems, send mail to companion dash discuss at opensolaris dot org, and we'll be happy to help you through.

Contribution process:

1. Subscribe to the integration alias, if you have not done so already. companion dash integrate at opensolaris dot org
2. Create or update a METADATA file for your package. An example is found in /usr/src/cmd/global/METADATA.
   The METADATA files will be used to generate a listing of the Companion content.
3. Legal Review --New packages require a legal review. Updates to an existing packages may also require a legal review.
   You should be aware of possible patent or encryption issues.
   If your software is bundled with another OpenSource distribution, there's a good chance we'll be able to take it. Notify the SFW CTeam sfw underline cteam dash ext at sun dot com of your plans. The CTeam lead will handle the legal review and advise on any patent or encryption issues.
4. You will need to have a Contributor Agreement on file for the files you create for the build infrastructure.
5. Test the packages generated by your build, including testing within a zone.
6. Get a codereview -- send mail to companion dash discuss at opensolaris dot org, to solicit comments on your code. If there is a maintainer for the package you're modifying, request a review from them directly. Include the following details for your reviewers:
   • Where did you get your bits?
   • How did you verify that the bits are correct?
   • What changes did you make?
     A diff against the main distribution as well as the exact changes you're making to the companion gate are helpful. If your changes are small enough, include a simple diff in your email to companion-discuss. Longer codereviews should be hosted on the web. http://cr.grommit.com is available if you don't have your own site available.
     webrev is a useful tool for reviewing changes. You can download a beta version of webrev that works with svn workspaces.
   • What makefile and packaging changes did you make?
   • What testing did you do ?
   • Have you done a full build of the gate to ensure that your changes build correctly and that they haven't broken anything else?
7. For new packages, fill out the checklist.
   A checklist is not required for a simple rev of an existing package.
   You should submit a checklist for complex updates .
   Send the checklist to the SFW Cteam, SFW underline Cteam dash ext at sun dot com.
   The team will contact you with questions or send you an approval.
   
8. Request integration approval: send request to integrate your change to the integration alias. companion dash integrate at sun dot com
   Include the following information in your request to integrate, RTI.
   • the name and email address of your code reviewer
   • the name of the license the software is distributed under and whether a legal review was done.
   • brief description of your changes and/or a pointer to your code review materials
9. Be sure that you have affiliated with the project. Click on the Affiliate link found at the Companion page.
10. The gatekeeper will open the gate for your approved integration request.
11. Commit your changes to the source gate. The putback comments should be short.

Contribution Guidelines:

• Intertwined software

  If you have a package that may effect other software within the companion, you should build and try everything which might use your software. If changes are required to the build environment of other components, you're responsible for making those changes.

• Zones-friendly packaging

  Software should be packaged to be Zones-friendly. Some specific details are covered in the Packag ing guidelines section, but you should try to run the software in a zone and make sure there are no surprises. The folks in the Zones Community will be happy to help with any questions.

• Packaging guidelines:

  Software delivered through the Companion consolidation is generally delivered in the /opt/sfw set of directories. There are subdirectories for bin, lib, man, and other common locations for software delivery.

  To allow /opt/sfw to be shared among multiple zones, we strongly recommend using /etc/opt/sfw for user-customizable configuration file location, and /var/opt/sfw for files which vary (e.g. logfiles) over the lifetime of the software. See filesystem(5) for more information.

  For software which delivers files into both root filesystems (e.g. /etc/opt) and mountable filesystems (e.g. /opt/sfw), two separate packages should be delivered. This allows more seamless operation of Diskless Clients and Zones.

• SMF integration

  If the software contains an init.d file, rc?.d file, inittab entry, or inetd.conf entry, you should consider creating an SMF manifest (or manifests) for the software and contributing it back to the authors/maintainers of the software. Check in the SMF Community for documentation and folks ready to help with any questions.

• Security

  This consolidation currently will not distribute software which installs setuid binaries.

  Make sure that you download software source from the real maintainers of that software. Validate the files you downloaded against any checksums provided. If you have the inclination, help keep an eye on the source for trojans and report any security problems you encounter to the software's maintaners.

  Try to be proactive in keeping components up to date with current security fixes/enhancements.

Component ownership:

In order to keep software up to date and encourage the highest quality standards possible for companion software, we're instituting a policy of component ownership. A component owner is the primary maintainer of a piece of software in the CCD consolidation.

You must have done at least one successful putback to a component in order to apply for component ownership. To apply for component ownership, email the SFW CTeam: sfw_cteam-ext AT sun.com. Two successful putbacks to an unowned component will make you a default owner.

The responsibilities of a component owner are:

• code reviewer

  Review code and makefile changes for others who want to contribute updates/changes to software you own.

• regular component updates

  Keep software relatively up-to-date with the stable (working) release tree and critical patches for that component. Expect to check for updates approximately quarterly.

• upstream contributions

  Form a relationship with the authors/maintainers of the software you own. Help improve the software by driving changes needed for the CCD package into the main source tree. Improvements to the upstream software help everyone!

• proactive security updates

  If you hear about or are told about security fixes, try to proactively update your component as soon as possible.