Wiki code for Contributor Guidelines

Hide Line numbers
1: 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!
2: 
3: === Eligible software:
4: 
5:  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.
6: 
7: === Getting started:
8: 
9: 1. Check the [[ current content list >>content]].
10: 1. Learn how to build software in the CCD by reading the [[build instructions >>buildccd]].
11: 1. Locate a piece of software you’d like to contribute or update.
12: 1. Take a look at the [[Contribution Process>>#contrib_process]] for a preview into what happens after you’ve got the code working.
13: 1. Read the [[Contribution Guidelines>>#contrib_guidelines]] below for requirements, suggestions, and hints about the technical process of incorporating software in the build process.
14: 1. If you’re updating a piece of software,
15: 11. Replace the source tarball with the updated version
16: 11. To get things building, you’ll need to update {{code}}Makefile.sfw{{/code}} and {{code}}install-sfw{{/code}} to point to the latest versions. You may need to also modify configure and compile options, or remove old patches applied.
17: 11. 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. {{code}}DIST*.sfw{{/code}} and {{code}}README.*{{/code}}.
18: 11. Check for new excecutables, docs, libraries, etc. added by the new version, and include them in the appropriate package definitions in {{code}}usr/src/pkgdefs{{/code}}.
19: 11. 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!
20: 1. If you’re contributing a new piece of software,
21: 11. Look at the [[Contribution Process>>#contrib_process]] again, and get the legal process started before embarking on a task that might be thwarted by lawyers.
22: 11. Get the software compiling on Solaris, and take notes about the steps you took.
23: 11. 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>>#contrib_guidelines]].
24: 1. If you’re running into problems, send mail to [[companion-discuss@opensolaris.org>>mailto:companion-discuss@opensolaris.org]], and we’ll be happy to help you through.
25: 
26: === Contribution process:
27: 
28: 1. Subscribe to the integration alias, if you have not done so already. [[ companion-integrate@opensolaris.org>>http://mail.opensolaris.org/mailman/listinfo/companion-integrate]]
29: 1. Create or update a [[METADATA >>attach:METADATA]]file for your package. An example is found in /usr/src/cmd/global/METADATA.
30:  The METADATA files will be used to generate a listing of the Companion content.
31: 1. Legal Review ~--New packages require a legal review. Updates to an existing packages may also require a legal review.
32:  You should be aware of possible patent or encryption issues.
33:  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_cteam-ext@sun.com>>mailto:
34:      sfw_cteam-ext@sun.com]] of your plans. The CTeam lead will handle the legal review and advise on any patent or encryption issues.
35: 1. You will need to have a [[Contributor Agreement>>http::/opensolaris.org/os/about/sun_contributor_agreement]] on file for the files you create for the build infrastructure.
36: 1. Test the packages generated by your build, including testing within a zone.
37: 1. Get a codereview ~-- send mail to [[companion-discuss@opensolaris.org>>mailto:companion-discuss@opensolaris.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:
38: 1* Where did you get your bits?
39: 1* How did you verify that the bits are correct?
40: 1* What changes did you make?
41: 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>>http://cr.grommit.com]] is available if you don’t have your own site available.
42: [[webrev>>attach:webrevinfo]] is a useful tool for reviewing changes. You can download a beta version of [[webrev>>http://dlc.sun.com/osol/companion/downloads/webrev.tar.bz2]] that works with svn workspaces.
43: 1* What makefile and packaging changes did you make?
44: 1* What testing did you do ?
45: 1* Have you done a full build of the gate to ensure that your changes build correctly and that they haven’t broken anything else?
46: 1. For new packages, fill out the [[checklist>>checklist]].
47:  A checklist is not required for a simple rev of an existing package.
48:  You should submit a checklist for complex updates .
49:  Send the checklist to the SFW Cteam, [[SFW_Cteam-ext@sun.com.
50:  The team will contact you with questions or send you an approval.
51: >>mailto:
52:         sfw_cteam-ext@sun.com]]
53: 1. Request integration approval: send request to integrate your change to the integration alias. [[companion-integrate@sun.com>>mailto:
54:      companion-integrate@sun.com]]
55:  Include the following information in your request to integrate, RTI.
56: 1* the name and email address of your code reviewer
57: 1* the name of the license the software is distributed under and whether a legal review was done.
58: 1* brief description of your changes and/or a pointer to your code review materials
59: 1. Be sure that you have affiliated with the project. Click on the Affiliate link found at the Companion page.
60: 1. The gatekeeper will open the gate for your approved integration request.
61: 1. Commit your changes to the source gate. The putback comments should be short.
62: 
63: === Contribution Guidelines:
64: 
65: * Intertwined software
66: 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.
67: * Zones-friendly packaging
68: 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>>Community Group zones.WebHome]] will be happy to help with any questions.
69: * Packaging guidelines:
70: Software delivered through the Companion consolidation is generally delivered in the {{code}}/opt/sfw{{/code}} set of directories. There are subdirectories for {{code}}bin{{/code}}, {{code}}lib{{/code}}, {{code}}man{{/code}}, and other common locations for software delivery.
71: To allow {{code}}/opt/sfw{{/code}} to be shared among multiple zones, we strongly recommend using {{code}}/etc/opt/sfw{{/code}} for user-customizable configuration file location, and {{code}}/var/opt/sfw{{/code}} for files which vary (e.g. logfiles) over the lifetime of the software. See {{code}}filesystem{{/code}}(5) for more information.
72: For software which delivers files into both root filesystems (e.g. {{code}}/etc/opt{{/code}}) and mountable filesystems (e.g. {{code}}/opt/sfw{{/code}}), two separate packages should be delivered. This allows more seamless operation of Diskless Clients and Zones.
73: * SMF integration
74: If the software contains an {{code}}init.d{{/code}} file, {{code}}rc?.d{{/code}} file, {{code}}inittab{{/code}} entry, or {{code}}inetd.conf{{/code}} 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>>Community Group smf.WebHome]] for documentation and folks ready to help with any questions.
75: * Security
76: This consolidation currently will not distribute software which installs setuid binaries.
77: 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.
78: Try to be proactive in keeping components up to date with current security fixes/enhancements.
79: 
80: === Component ownership:
81: 
82:  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.
83: 
84: 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: {{code}}sfw_cteam-ext{{/code}} AT {{code}}sun.com{{/code}}. Two successful putbacks to an unowned component will make you a default owner.
85: 
86: The responsibilities of a component owner are:
87: 
88: * //code reviewer//
89: Review code and makefile changes for others who want to contribute updates/changes to software you own.
90: * //regular component updates//
91: 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.
92: * //upstream contributions//
93: 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!
94: * //proactive security updates//
95: If you hear about or are told about security fixes, try to proactively update your component as soon as possible.
OpenSolaris

Top Menu

Wiki code for Contributor Guidelines

Search

Collectives

Community Group

Project

User Group

Subsites

Project companion Pages
