Contributing code back to OpenACS

Prev	Chapter 14. CVS Guidelines	Next

There are three main ways to contribute code to OpenACS:

To contribute a small fix, if you do not have a developer account, submit a patch.
If you are making many changes, or would like to become a direct contributor, send mail to the Core Team asking for commit rights. You can then commit code directly to the repository:
1. Use one of the checkout methods described above to get files to your system. This takes the place of steps 1 and 2 in the section called “Installation Option 2: Install from tarball”. Continue setting up the site as described there.
2. Fix bugs and add features.
3. Commit that file (or files):
```
cvs commit -m "what I did and why" filename
```
  Because this occurs in your personal checkout and not an anonymous one, this commit automagically moves back upstream to the Mother Ship repository at cvs.openacs.org. The names of the changed files, and your comments, are sent to a mailing list for OpenACS developers. A Core Team developer may review or roll back your changes if necessary.
4. Confirm via the OpenACS CVS browser that your changes are where you intended them to be.
Add a new package. Contact the Core Team to get approval and to get a module alias created.
1. Check out acs-core on the HEAD branch. (Weird things happen if you add files to a branch but not to HEAD):
```
cd /tmp
cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core
```
  Copy your package directory from your working directory to this directory. Make sure not to copy any CVS directories.
```
cp -r /var/lib/aolserver/service0/packages/newpackage /tmp/openacs-4/packages
```
  Import the package into the cvs.openacs.org cvs repository:
```
cd /tmp/openacs-4/packages/newpackage
cvs import -m "Initial import of newpackage" openacs-4/packages/newpackage myname newpackage-0-1d
```
2. Add the new package to the modules file. (An administrator has to do this step.) On any machine, in a temporary directory:
```
cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
cd CVSROOT
emacs modules
```
  Add a line of the form:
```
photo-album-portlet openacs-4/packages/photo-album-portlet
```
  Commit the change:
```
cvs commit -m "added alias for package newpackage" modules
```
  This should print something like:
  cvs commit: Examining .
  **** Access allowed: Personal Karma exceeds Environmental Karma.
  Checking in modules;
  /cvsroot/CVSROOT/modules,v <-- modules
  new revision: 1.94; previous revision: 1.93
  done
  cvs commit: Rebuilding administrative file database
3. Although you should add your package on HEAD, you should do package development on the latest release branch that your code is compatible with. So, after completing the import, you may want to branch your package:
```
cd /var/lib/aolserver/service0/packages/newpackage
cvs tag -b oacs-5-1
```
4. See the section called “How to package and release an OpenACS Package”
Note
Some packages are already in cvs at openacs-4/contrib/packages. Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the contrib directory un-necessary. If you are working on a contrib package, you should move it to /packages. This must be done by an OpenACS administrator. On cvs.openacs.org:
1. ```
cp -r /cvsroot/openacs-4/contrib/packages/package0 /cvsroot/openacs-4/packages
```
2. Update the modules file as described above.
3. Remove the directory from cvs in the old location using cvs rm. One approach for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done

Rules for Committing Code to the OpenACS repository

CVS commit procedures are governed by TIP (Technical Improvement Proposal) #61: Guidelines for CVS committers

Which branch?
1. For core packages, new features should always be committed on HEAD, not to release branches.
2. For core packages, bug fixes should be committed on the current release branch whenever applicable.
3. For non-core packages, developers should work on a checkout of the release branch of the lastest release. For example, if OpenACS 5.1.0 is released, developers should work on the oacs-5-1 branch. When oacs-5-2 is branched, developers should continue working on oacs-5-1 until OpenACS 5.2.0 is actually released.
4. The current release branch is merged back to HEAD after each dot release.
New packages should be created in the /packages directory and the maturity flag in the .info file should be zero. This is a change from previous policy, where new packages went to /contrib/packages)
Code
1. Only GPL code and material should be committed to the OpenACS CVS repository (cvs.openacs.org)
2. Code should only be reformatted when functionality is changed, e.g. when you change control flow and reindent to reflect it.
3. Database upgrade scripts should only span one release increment, and should follow Naming Database Upgrade Scripts .
4. Database upgrade scripts should never go to the release version, e.g., should always have a letter suffix such as d1 or b1.
5. CVS commit messages should be intelligible in the context of Changelogs. They should not refer to the files or versions.
6. CVS commit messages and code comments should refer to bug, tip, or patch number if appropriate, in the format "resolves bug 11", "resolves bugs 11, resolves bug 22". "implements tip 42", "implements tip 42, implements tip 50", "applies patch 456 by User Name", "applies patch 456 by User Name, applies patch 523 by ...".
When to TIP
1. A TIP is a Techical Improvement Proposal ( more information ). A proposed change must be approved by TIP if:
  1. It changes the core data model, or
  2. It will change the behavior of any core package in a way that affects existing code (typically, by changing public API), or
  3. It is a non-backwards-compatible change to any core or standard package.
2. A proposed change need not be TIPped if:
  1. it adds a new function to a core package in a way that:
    does not change the backwards-compatibility of public API functions.
    does not change the data model
    has no negative impact on performance
  2. it changes private API, or
  3. it is a change to a non-core, non-standard package
Tags
1. When a package is released in final form, the developer shall tag it "packagename-x-y-z-final" and "openacs-x-y-compat". x-y should correspond to the current branch. If the package is compatible with several different core versions, several compat tags should be applied.
2. When OpenACS core is released, the openacs-x-y-z-final tag shall be applied to all compat packages.
For example, adding a new API function wouldn't require a TIP. Changing an existing API function by adding an optional new flag which defaults to no-effect wouldn't require a TIP. Added a new mandatory flag to an existing function would require a TIP.

Reasons

We don't currently have clear standards for committing code.

Rule 1.3: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.

Rule 3.4: If an upgrade script ends with the final release number, then if a problem is found in a release candidate it cannot be addressed with another upgrade script. E.g., the last planned upgrade script for a package previously in dev 1 would be upgrade-2.0.0d1-2.0.0b1.sql, not upgrade-2.0.0d1-2.0.0.sql. Note that using rc1 instead of b1 would be nice, because that's the convention with release codes in cvs, but the package manager doesn't support rc tags.

Rule 5.1: Reason 1: The packagename tag is a permanent, static tag that allows for future comparison. The compat tag is a floating tag which is used by the repository generator to determine the most recent released version of each package for each core version. This allows package developers to publish their releases to all users of automatic upgrade without any intervention from the OpenACS release team.Reason 2: The compat tags allows CVS users to identify packages which have been released since the last core release.Reason 3: The compat tag or something similar is required to make Rule 6 possible.

Rule 5.2: This allows OpenACS developers who are creating extensively customized sites to branch from a tag which is stable, corresponds to released code instead of development code, and applies to all packages. This tag can be used to fork packages as needed, and provides a common ancestor between the fork and the OpenACS code so that patches can be generated.

Informal Guidelines

Informal guidelines which may be obsolete in places and should be reviewed:

Before committing to cvs you must submit a bug report and patch to the OpenACS bug tracker . The only exceptions to this rule are for package maintainers committing in a package they are maintaining and for members of the core team.
If you are committing a bug fix you need to coordinate with the package maintainer. If you are a maintainer then coordinate with any fellow maintainers.
If you are to commit a new feature, an architecture change, or a refactoring, you must coordinate with the OpenACS core team first. Also, such changes should have a discussion in the forums to allow for feedback from the whole community.
If you are changing the data model you *must* provide an upgrade script and bump up the version number of the package.
Consider any upgradability ramifications of your change. Avoid changing the contract and behaviour of Tcl procedures. If you want to build a new and clean API consider deprecating the old proc and making it invoke the new one.
Never rush to commit something. Before committing double check with cvs diff what exactly you are committing.
Always accompany a commit with a brief but informative comment. If your commit is related to bug number N and/or patch number P, indicate this in the commit comment by including "bug N" and/or "patch P". This allows us to link bugs and patches in the Bug Tracker with changes to the source code. For example suppose you are committing a patch that closes a missing HTML tag, then an appropriate comment could be "Fixing bug 321 by applying patch 134. Added missing h3 HTML close tag".
Commit one cohesive bug fix or feature change at a time. Don't put a bunch of unrelated changes into one commit.
Before you throw out or change a piece of code that you don't fully understand, use cvs annotate and cvs log on the file to see who wrote the code and why. Consider contacting the author.
Test your change before committing. Use the OpenACS package acs-automated-testing to test Tcl procedures and the tool Tclwebtest to test pages
Keep code simple, adhere to conventions, and use comments liberally.
In general, treat the code with respect, at the same time, never stop questioning what you see. The code can always be improved, just make sure you change the code in a careful and systematic fashion.

Prev	Home	Next
OpenACS CVS Concepts	Up	Additional Resources for CVS