<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" 'http://www.w3.org/TR/html4/loose.dtd"'>
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>CVS Guidelines</title><link rel="stylesheet" type="text/css" href="openacs.css"><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"><link rel="home" href="index.html" title="OpenACS Core Documentation"><link rel="up" href="eng-standards.html" title="Chapter 12. Engineering Standards"><link rel="previous" href="style-guide.html" title="OpenACS Style Guide"><link rel="next" href="eng-standards-versioning.html" title="Release Version Numbering"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><a href="http://openacs.org"><img src="/doc/images/alex.jpg" style="border:0" alt="Alex logo"></a><table width="100%" summary="Navigation header" border="0"><tr><td width="20%" align="left"><a accesskey="p" href="style-guide.html">Prev</a> </td><th width="60%" align="center">Chapter 12. Engineering Standards</th><td width="20%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="cvs-guidelines"></a>
CVS Guidelines
</h2></div></div></div><div class="authorblurb"><div class="cvstag">($Id: cvs-guidelines.html,v 1.16 2024/09/11 06:15:47 gustafn Exp $)</div><p>
By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, and Jade Rubick.
</p>
OpenACS docs are written by the named authors, and may be edited
by OpenACS documentation staff.
</div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="using-cvs-with-openacs"></a>Using CVS with OpenACS</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1383"></a>Getting Started</h4></div></div></div><p>
All OpenACS code is available anonymously. To get code
anonymously, use the parameter
<code class="computeroutput">-d:pserver:anonymous@cvs.openacs.org:/cvsroot</code> immediately after <code class="computeroutput">cvs</code> in a cvs command to check out or export code.
</p><p>
If you are an OpenACS developer, you should check out code so
that you or any other developer can commit it. To do this, use
the parameter
<code class="computeroutput">-d:ext:cvs.openacs.org:/cvsroot</code>
immediately after <code class="computeroutput">cvs</code> in
checkout commands. This will create a local checkout directory
that uses cvs.openacs.org but does not specify the user. By
default, it will use your local account name as the user, so if
you are logged in as "foobar" it will try to check out and
commit as if you had specified
<code class="computeroutput">:ext:foobar@cvs.openacs.org:/cvsroot</code>. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts.
</p><p>
OpenACS.org supports non-anonymous cvs access only over ssh, so you
must have <code class="computeroutput">CVS_RSH=ssh</code> in your
environment. (Typically this is accomplished by putting
<code class="computeroutput">export CVS_RSH=ssh</code> into
<code class="computeroutput">~/.bash_profile</code>.). If your local
account name does not match your cvs.openacs.org account name, create a
file <code class="computeroutput">~/.ssh/config</code> with an entry
like:
</p><pre class="programlisting">Host cvs.openacs.org
User joel
</pre><p>
With this setup, you will be asked for your password with
each cvs command. To avoid this, set up ssh certificate
authentication for your OpenACS account. (<a class="ulink" href="https://www.digitalocean.com/community/tutorials/how-to-configure-ssh-key-based-authentication-on-a-linux-server" target="_top">More
information</a>)
</p><p>
You may want to set some more default actions for CVS usage.
To do so, create the file
<code class="computeroutput">~/.cvsrc</code> with the contents:
</p><pre class="screen"><span class="action"><span class="action">cvs -z6
cvs -q</span></span></pre><p><code class="computeroutput">-z6</code> speeds up cvs access over the network quite a bit by enabling compressed
connection by default. <code class="computeroutput">-q</code> suppresses some verbose output from commands. For example, it makes the output of <code class="computeroutput">cvs up</code> much easier to read.</p><div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div><p>Administrator Note: These are the steps to grant CVS commit rights to a user:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>Create the user's account. On cvs.openacs.org:</p><pre class="screen"><span class="action"><span class="action">sudo bash
adduser --add_extra_groups cvs --gecos "<span class="replaceable"><span class="replaceable">Real Name</span></span>" --shell <span class="replaceable"><span class="replaceable">/bin/bash </span></span> <span class="replaceable"><span class="replaceable">username</span></span>
</span></span></pre></li><li class="listitem"><p>Grant cvs access to the user account. On any machine,
in a temporary directory:
</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
cd CVSROOT
emacs avail</span></span></pre><p>Add an avail line of the form:</p><pre class="programlisting">avail|<span class="replaceable"><span class="replaceable">username</span></span>|openacs-4</pre><pre class="screen"><span class="action"><span class="action">cvs commit -m "added commit on X for username" avail</span></span></pre></li></ol></div></div><div class="sidebar"><div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div><p>Branimir suggests an additional level of abstraction. If you put</p><pre class="programlisting">Host cvs-server
HostName cvs.openacs.org
User <span class="replaceable"><span class="replaceable">yournamehere</span></span></pre><p>into your <code class="computeroutput">~/.ssh/config</code> file, then you can use <code class="computeroutput">-d :ext:cvs-server:/cvsroot</code> instead of <code class="computeroutput">-d :ext:cvs.openacs.org:/cvsroot</code>. You can then change the definition of <code class="computeroutput">cvs-server</code> by changing one file instead of editing hundreds of <code class="computeroutput">CVSROOT/Repository</code> files.</p></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1384"></a>Checkout for Package Development</h4></div></div></div><p>If you are actively developing a non-core package, you
should work from the latest core release branch. Currently this
is oacs-5-9. This ensures that you are working on top
of a stable OpenACS core, but still allows you to commit feature
changes to non-core packages. To check out all packages,</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-9 openacs-4</span></span></pre><p>If you work in the directories created with this command, all of your
cvs updates and commits will be confined to the oacs-5-9
branch. Your work will be merged back to HEAD for you
with each release.</p><p>Because the entire openacs-4 directory is large, you may
want to use only acs-core plus some specific modules. To do
this, check out core first:</p><pre class="screen"><span class="action"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-9 checkout acs-core</span></span></pre><p>Then add modules as needed:</p><pre class="screen"><span class="action"><span class="action">cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages
cvs up -d <span class="replaceable"><span class="replaceable">packagename</span></span></span></span></pre><p>... where <span class="replaceable"><span class="replaceable">packagename</span></span> is the
name of the package you want. Visit the <a class="ulink" href="http://openacs.org/packages" target="_top"> Package
Inventory</a> and <a class="ulink" href="http://openacs.org/projects/openacs/packages/" target="_top">Package
maintainers and status</a> for a list of available
packages and their current state.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1385"></a>Checkout for Core Development</h4></div></div></div><p>If you are actively developing packages in the OpenACS
Core, work from the HEAD branch. HEAD is used for active
development of the next version of core OpenACS. It may be very
buggy; it may not even install correctly. Do not use this branch for
development of non-core features unless your work depends on some
of the HEAD core work. To check out HEAD, omit the
<code class="computeroutput">-r</code> tag.</p><p></p><p>To check out HEAD for development, which requires an OpenACS developer account:</p><pre class="screen"><span class="action"><span class="action">cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre><p>To check out HEAD anonymously:</p><pre class="screen"><span class="action"><span class="action">cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1386"></a>Checkout .LRN</h4></div></div></div><p>
.LRN consists of a given version OpenACS core, plus a set of
packages. These are collectively packages together to form a
distribution of .LRN. F .LRN 2.0.0 sits on top of OpenACS 5.0.0.
.LRN also uses an OpenACS install.xml file during installation;
this file is distributed within the dotlrn package and must be
moved. To get a development checkout of .LRN in the subdirectory
<code class="literal">dotlrn</code>:
</p><pre class="screen"><span class="action"><span class="action">cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 acs-core
mv openacs-4 dotlrn
cd dotlrn/packages
cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 dotlrn-all
mv dotlrn/install.xml ..</span></span></pre></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="working-with-cvs"></a>Working with CVS</h4></div></div></div><p>
Once you have a checkout you can use some commands to track
what has changed since you checked out your copy. <code class="computeroutput">cvs -n update</code> does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS.
</p><p>To update your files, use <code class="computeroutput">cvs update</code>. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.</p></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="openacs-cvs-concepts"></a>OpenACS CVS Concepts</h3></div></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1387"></a>Modules</h4></div></div></div><p>
All OpenACS code resides within a single CVS module, <code class="computeroutput">openacs-4</code>. (The openacs-4 directory contains code for all versions of OpenACS 4 and later, and .LRN 1 and later.) Checking out this module retrieves all OpenACS code of any type. For convenience, subsets of <code class="computeroutput">openacs-4</code> are repackaged as smaller modules.</p><p>
<code class="computeroutput">acs-core</code> contains only critical common
packages. It does not have any user applications, such as forums,
bug-tracker, calendar, or ecommerce. These can be added at
any time.
</p><p>The complete list of core packages is:</p><pre class="programlisting">acs-admin
acs-api-browser
acs-authentication
acs-automated-testing
acs-bootstrap-installer
acs-content-repository
acs-core-docs
acs-kernel
acs-lang
acs-mail
acs-messaging
acs-reference
acs-service-contract
acs-subsite
acs-tcl
acs-templating
ref-timezones search</pre><p>
<code class="computeroutput">dotlrn-all</code> contains the packages required, in combination with acs-core, to run the .LRN system.
</p><p>
<code class="computeroutput">project-manager-all</code> contains the packages required, in combination with acs-core, to run the project-manager package.
</p><p>
Each OpenACS package (i.e., directory in <code class="computeroutput">openacs-4/packages/</code>) is also aliased as a module of the same name.
</p></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1388"></a>
Tags and Branches
</h4></div></div></div><p>
Tags and Branches look similar in commands, but behave differently. A tag is a fixed point on a branch. Check out
a tag to get a specific version of OpenACS. Check out a branch to
get the most current code for that major-minor version (e.g., 5.0.x
or 5.1.x). You can only commit to a branch, not a tag, so check out
a branch if you will be working on the code. </p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p><code class="computeroutput">openacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code>
tags mark final releases of OpenACS. This tag is applied to the acs-core files for an OpenACS core release, and to the latest released versions of all other packages at the time of release. Example: <code class="computeroutput">openacs-5-0-4-final</code>.
</p></li><li class="listitem"><p><code class="computeroutput">dotlrn-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code>
tags mark final releases of .LRN. These tags apply only to .LRN packages. Example: <code class="computeroutput">dotlrn-2-0-1-final</code>
</p></li><li class="listitem"><p><code class="computeroutput"><span class="replaceable"><span class="replaceable">packagename</span></span>-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-<span class="replaceable"><span class="replaceable">z</span></span>-final</code>
tags apply to releases of individual packages. For example, <code class="computeroutput">calendar-2-0-0-final</code> is a tag that will retrieve only the files in the calendar 2.0.0 release. It applies only to the
calendar package. All non-core, non-dotlrn packages should have a
tag of this style, based on the package name. Many packages have
not been re-released since the new naming convention was adopted
and so don't have a tag of this type.
</p></li><li class="listitem"><p><code class="computeroutput">openacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span>-compat</code> tags point to the most recent released version of OpenACS <span class="replaceable"><span class="replaceable">X</span></span>.<span class="replaceable"><span class="replaceable">Y</span></span>.
It is similar to openacs-x-y-z-compat, except that it will
always get the most recent dot-release of Core and the
most recent compatible, released version of all other
packages. All of the other tag styles should be static,
but -compat tags may change over time. If you want version
5.0.4 exactly, use the openacs-5-0-4-final tag. If you want the best newest released code in the 5.0.x release series and you want to upgrade within 5.0.x later, use the compat tag.
</p><p>
For example, if you check out the entire tree with -r
openacs-5-0-compat, you might get version 5.0.4 of each OpenACS
core package, version 2.0.1 of calendar, version 2.0.3 of each .LRN
package, etc. If you update the checkout two months later, you
might get version 5.0.5 of all OpenACS core packages and version
2.1 of calendar.
</p></li><li class="listitem"><p>oacs-<span class="replaceable"><span class="replaceable">x</span></span>-<span class="replaceable"><span class="replaceable">y</span></span> is a <span class="emphasis"><em>branch, </em></span>, not a tag. All core packages in the 5.0 release series (5.0.0, 5.0.1, 5.0.2, etc) are also on the oacs-5-0 branch. Similarly, OpenACS core packages for 5.1.0 are on the oacs-5-1 branch.</p><p>These branches are used for two purposes. OpenACS
Core packages on these branches are being tidied up for
release. Only bug fixes, not new features, should be
added to core packages on release branches. For all other
packages, release branches are the recommended location
for development. For example, if you are working on
calendar, which is compatible with OpenACS 5.0 but not
5.1, work on the oacs-5-0 branch.</p></li><li class="listitem"><p><code class="computeroutput">HEAD</code> is a branch used
for development of core packages.</p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="contributing-code"></a>Contributing code back to OpenACS</h3></div></div></div><p>There are three main ways to contribute code to OpenACS:</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>To contribute a small fix, if you do not have a developer account, submit a <a class="ulink" href="http://openacs.org/bugtracker/openacs/patch-submission-instructions.htm" target="_top">patch</a>.</p></li><li class="listitem"><p>If you are making many changes, or would like to become a direct contributor, send mail to <a class="ulink" href="mailto:oct@openacs.org" target="_top">the Core Team</a> asking for commit rights. You can then commit code directly to the repository:</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>Use one of the checkout methods described above to get files to your system. This takes the place of steps 1 and 2 in <a class="xref" href="openacs.html#install-from-tarball" title="Installation Option 2: Install from tarball">the section called “Installation Option 2: Install from tarball”</a>. Continue setting up the site as described there.</p></li><li class="listitem"><p>Fix bugs and add features.</p></li><li class="listitem"><p>
Commit that file (or files): </p><pre class="screen"><span class="action"><span class="action">cvs commit -m "what I did and why" filename</span></span></pre><p>
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.
</p></li><li class="listitem"><p>
Confirm via the <a class="ulink" href="http://cvs.openacs.org/browse/OpenACS/openacs-4/" target="_top">
OpenACS CVS browser </a>
that your changes are where you intended them to be.
</p></li></ol></div></li><li class="listitem"><p>Add a new package. Contact the <a class="ulink" href="mailto:oct@openacs.org" target="_top">Core Team</a> to get approval and to get a module alias created.</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><p>
Check out acs-core on the HEAD branch. (Weird things happen if you add files to a branch but not to HEAD):</p><pre class="screen"><span class="action"><span class="action">cd /tmp
cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</span></span></pre><p>Copy your package directory from your working directory to this directory. Make sure not to copy any CVS directories.</p><pre class="screen"><span class="action"><span class="action">cp -r /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span> /tmp/openacs-4/packages</span></span></pre><p>Import the package into the cvs.openacs.org cvs repository:</p><pre class="screen"><span class="action"><span class="action">cd /tmp/openacs-4/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span>
cvs import -m "Initial import of <span class="replaceable"><span class="replaceable">newpackage</span></span>" openacs-4/packages/newpackage <span class="replaceable"><span class="replaceable">myname</span></span> <span class="replaceable"><span class="replaceable">newpackage-0-1d</span></span></span></span></pre></li><li class="listitem"><p>Add the new package to the modules file. (An administrator has to do this step.) On any machine, in a temporary directory:</p><pre class="screen"><span class="action"><span class="action">cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
cd CVSROOT
emacs modules</span></span></pre><p>Add a line of the form:</p><pre class="programlisting"><span class="replaceable"><span class="replaceable">photo-album-portlet</span></span> openacs-4/packages/<span class="replaceable"><span class="replaceable">photo-album-portlet</span></span></pre><p>Commit the change:</p><pre class="screen"><span class="action"><span class="action">cvs commit -m "added alias for package <span class="replaceable"><span class="replaceable">newpackage</span></span>" modules</span></span></pre><p>This should print something like:</p><div class="literallayout"><p>cvs commit: Examining .<br>
**** Access allowed: Personal Karma exceeds Environmental Karma.<br>
Checking in modules;<br>
/cvsroot/CVSROOT/modules,v <-- modules<br>
new revision: 1.94; previous revision: 1.93<br>
done<br>
cvs commit: Rebuilding administrative file database</p></div></li><li class="listitem"><p>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:</p><pre class="programlisting">cd /var/lib/aolserver/<span class="replaceable"><span class="replaceable">service0</span></span>/packages/<span class="replaceable"><span class="replaceable">newpackage</span></span>
cvs tag -b <span class="replaceable"><span class="replaceable">oacs-5-1</span></span></pre></li><li class="listitem"><p>See <a class="xref" href="releasing-package.html" title="How to package and release an OpenACS Package">the section called “How to package and release an OpenACS Package”</a></p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Some packages are already in cvs at <code class="computeroutput">openacs-4/contrib/packages</code>. Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the <code class="computeroutput">contrib</code> directory un-necessary. If you are working on a <code class="computeroutput">contrib</code> package, you should move it to <code class="computeroutput">/packages</code>. This must be done by an OpenACS administrator. On cvs.openacs.org:</p><div class="orderedlist"><ol class="orderedlist" type="a"><li class="listitem"><pre class="programlisting">cp -r /cvsroot/openacs-4/contrib/packages/<span class="replaceable"><span class="replaceable">package0</span></span> /cvsroot/openacs-4/packages</pre></li><li class="listitem"><p>Update the modules file as described above.</p></li><li class="listitem"><p>Remove the directory from cvs in the old location using <code class="computeroutput">cvs rm</code>. One approach <code class="computeroutput">for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done</code></p></li></ol></div></div></li></ol></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="Commit_Rules"></a>
Rules for Committing Code to the OpenACS repository
</h4></div></div></div><p>
CVS commit procedures are governed by
<a class="ulink" href="http://openacs.org/forums/message-view?message_id=185506" target="_top">
TIP (Technical Improvement Proposal) #61: Guidelines for CVS committers
</a>
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Which branch?
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
For core packages, new features should always be
committed on HEAD, not to release branches.
</p></li><li class="listitem"><p>
For core packages, bug fixes should be committed on the
current release branch whenever applicable.
</p></li><li class="listitem"><p>
For non-core packages, developers should work on a
checkout of the release branch of the latest 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.
</p><p>
<span class="emphasis"><em>
Reason: First, this ensures that developers are working against stable core code. Second, it ensures that new package releases are available to OpenACS users immediately.</em></span></p></li><li class="listitem"><p>
The current release branch is merged back to HEAD after
each dot release.
</p></li></ol></div></li><li class="listitem"><p>
New packages should be created in the
<code class="computeroutput">
/packages
</code>
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)
</p></li><li class="listitem"><p>
Code
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
Only GPL code and material should be committed to the
OpenACS CVS repository (cvs.openacs.org)
</p></li><li class="listitem"><p>Do not mix formatting changes with code changes. Instead, make a formatting-only change which does not affect the logic, and say so in the commit comment. Then, make the logic change in a separate commit. <span class="emphasis"><em>Reason: This makes auditing and merging code much easier.</em></span>
</p></li><li class="listitem"><p>
Database upgrade scripts should only span one release
increment, and should follow
<a class="ulink" href="http://openacs.org/doc/current/eng-standards-versioning.html#naming-upgrade-scripts" target="_top">
Naming Database Upgrade Scripts
</a>
.
</p><p>
<span class="emphasis"><em>Reason: 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.</em></span>
</p></li><li class="listitem"><p>
Database upgrade scripts should never go to the release
version, e.g., should always have a letter suffix such as d1 or
b1.
</p></li><li class="listitem"><p>
CVS commit messages should be intelligible in the context
of Changelogs. They should not refer to the files or
versions.
</p></li><li class="listitem"><p>
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
...".
</p></li></ol></div></li><li class="listitem"><p>
When to TIP
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
A TIP is a Technical Improvement Proposal (
<a class="ulink" href="http://openacs.org/forums/message-view?message_id=115576" target="_top">
more information
</a>
). A proposed change must be approved by TIP if:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
It changes the core data model, or
</p></li><li class="listitem"><p>
It will change the behavior of any core package in a way
that affects existing code (typically, by changing public API), or
</p></li><li class="listitem"><p>
It is a non-backwards-compatible change to any core or
standard package.
</p></li></ol></div></li><li class="listitem"><p>
A proposed change need not be TIPped if:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
it adds a new function to a core package in a way that:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
does not change the backwards-compatibility of public API
functions.
</p></li><li class="listitem"><p>
does not change the data model
</p></li><li class="listitem"><p>
has no negative impact on performance
</p></li></ol></div></li><li class="listitem"><p>
it changes private API, or
</p></li><li class="listitem"><p>
it is a change to a non-core, non-standard package
</p></li></ol></div></li></ol></div></li><li class="listitem"><p>
Tags
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
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.
</p><p>
<span class="emphasis"><em>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.</em></span>
</p></li><li class="listitem"><p>
When OpenACS core is released, the openacs-x-y-z-final
tag shall be applied to all compat packages.
</p><p>
<span class="emphasis"><em>
Reason: 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.
</em></span>
</p></li></ol></div><p>
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.
</p></li></ol></div></div><div class="sect3"><div class="titlepage"><div><div><h4 class="title"><a name="id1389"></a>
Informal Guidelines
</h4></div></div></div><p>
Informal guidelines which may be obsolete in places and should be reviewed:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
Before committing to cvs you must submit a bug report and
patch to the
<a class="ulink" href="http://openacs.org/bugtracker/openacs" target="_top">
OpenACS
bug tracker
</a>
. The only exceptions to this rule are
for
<a class="ulink" href="/projects/openacs/4.7/package_inventory" target="_top">
package
maintainers
</a>
committing in a package they are
maintaining and for members of the core team.
</p></li><li class="listitem"><p>
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.
</p></li><li class="listitem"><p>
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.
</p></li><li class="listitem"><p>
If you are changing the data model you *must* provide an
upgrade script and bump up the version number of the
package.
</p></li><li class="listitem"><p>
Consider any upgradability ramifications of your change.
Avoid changing the contract and behavior 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.
</p></li><li class="listitem"><p>
Never rush to commit something. Before committing double
check with cvs diff what exactly you are committing.
</p></li><li class="listitem"><p>
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".
</p></li><li class="listitem"><p>
Commit one cohesive bug fix or feature change at a time.
Don't put a bunch of unrelated changes into one commit.
</p></li><li class="listitem"><p>
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.
</p></li><li class="listitem"><p>
Test your change before committing. Use the OpenACS
package acs-automated-testing to test Tcl procedures and the tool
<a class="ulink" href="http://tclwebtest.sourceforge.net" target="_top">
Tclwebtest
</a>
to test pages
</p></li><li class="listitem"><p>
Keep code simple, adhere to conventions, and use comments
liberally.
</p></li><li class="listitem"><p>
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.
</p></li></ul></div></div></div><div class="sect2"><div class="titlepage"><div><div><h3 class="title"><a name="cvs-resources"></a>Additional Resources for CVS</h3></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
The
<a class="ulink" href="http://cvs.openacs.org/" target="_top">
OpenACS cvs web browser</a>
is a useful tools in understanding what is
happening with the code.
</p></li><li class="listitem"><p>
There is general information about CVS at
<a class="ulink" href="http://www.nongnu.org/cvs/" target="_top">
nongnu.org
</a>.
</p></li><li class="listitem"><p>
<a class="ulink" href="http://web.mit.edu/gnu/doc/html/cvs_20.html" target="_top">cvs manual</a>
</p></li><li class="listitem"><p>
<a class="ulink" href="http://cvsbook.red-bean.com/cvsbook.html" target="_top">Open Source Development with CVS, 3rd Edition</a>
</p></li><li class="listitem"><p>
<a class="ulink" href="http://www.piskorski.com/docs/cvs-conventions.html" target="_top">Piskorski's cvs refs</a>
</p></li><li class="listitem"><p>
<a class="ulink" href="http://openacs.org/doc/current/backups-with-cvs.html" target="_top">backup with cvs</a>
</p></li><li class="listitem"><p>
<a class="ulink" href="http://openacs.org/forums/message-view?message_id=178551" target="_top">merging 2 file hierarchies with cvs</a>
</p></li></ul></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="style-guide.html">Prev</a> </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right"> <a accesskey="n" href="eng-standards-versioning.html">Next</a></td></tr><tr><td width="40%" align="left">OpenACS Style Guide </td><td width="20%" align="center"><a accesskey="u" href="eng-standards.html">Up</a></td><td width="40%" align="right"> Release Version Numbering</td></tr></table><hr><address><a href="mailto:docs@openacs.org">docs@openacs.org</a></address></div><a name="comments"></a></body></html>