Introduction

These instructions are for advanced OpenACS developers who have cvs commit rights on the OpenACS cvs repository. If you are looking for instruction on how to checkout OpenACS from CVS - see our CVS Guidelines. To learn how you can contribute to the OpenACS project, see the Contribute page.

Guidelines

  • 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.

  • The workflow for the bug tracker (acutally issue track) is defined as follows:

  • 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.

  • The OpenACS cvs web is a useful tools in understanding what is happening with the code.

  • 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.

  • Details about the mechanics of committing code to the CVS repository at openacs.org can be found in this useful discussion by Jade Rubick. Here are some brief, practical points:

    1. You need to have a user account on the openacs.org box; someone will set that up for you.
    2. Set up the environment on your development box:
      CVS_RSH=ssh
      export CVS_RSH
    3. Instead of an anonymous CVS checkout, get a non-anonymous checkout:
      cvs -z3 -d :ext:your-user-name@openacs.org:/cvsroot co openacs-4
      for a HEAD version (include the proper "-r branch-tag" for a specific branch) 
      Using -d ext:your-user-name@openacs.org is evil because it makes it much harder to share a working directory with another user.

There is a better way to *never* have to type password, not even on
commit. (The following assumes that security policy disallows
passwordless RSA/DSA authentication, which is a trivial solution to the
problem).

1/ On the CVS server machine allow pserver access for commits, but only
if user is on localhost (trivial firewall rule)

2/ From the client machine establish an SSH tunnel

3/ use cvs login and the rest through the tunnel

If for some reason using pserver is not desirable, one could instead do
the following: Allow passwordless RSA/DSA auth. if the connection is
from localhost and then run ssh over ssh tunnel instead of pserver over
ssh tunnel.

--Branimir via Joel & Roc
    4. Edit or patch your files
    5. 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 openacs.org.
    6. Confirm via the OpenACS CVS browser that your changes are where you intended them to be.

  • Review this forum discussion for additional points regarding policies for CVS use during package development.
  • Notes on creating modules to go with new packages, and granting related permissions: 
    You need to add it to the modules file
in CVSROOT (edit them in a checkout and commit them,
never ever edit files directly in /cvsroot/CVSROOT).
log in to openacs.org...
cvs -d /cvsroot co CVSROOT
cd CVSROOT
emacs modules
add a line like:
photo-album-portlet openacs-4/packages/photo-album-portlet
for your new module
cvs commit -m "adding aliases for packages BLAH"

(this should print something like:
cvs commit: Examining .
**** Access allowed: Personal Karma exceeds Environmental Karma.
Checking in avail;
/cvsroot/CVSROOT/avail,v  <--  avail
new revision: 1.94; previous revision: 1.93
done
cvs commit: Rebuilding administrative file database
)

For giving someone karma on things edit the avail file
(same process really).  I don't think there is any real
need to ask permission to give someone commit on a particular module
and their commits go via email so if anything bad gets committed
it's likely it will get caught and fixed or rolled back).
-- Jeff Davis
  • Notes on CVS access 
    (1) Every user should have something like this in his .ssh/config

Host cvs-server
HostName server003.example.net
User cvsuser

(2) When checking out stuff from CVS people should always use -d
ext:cvs-server ...

-- Branimir