<?xml version='1.0' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
<!ENTITY % myvars SYSTEM "../variables.ent">
%myvars;
]>
<sect1 id="cvs-guidelines">
  <title>
    CVS Guidelines
  </title>
<authorblurb>
    <para><phrase role="cvstag">($Id: cvs.xml,v 1.6 2006/07/17 05:38:37 torbenb Exp $)</phrase></para>
   <para>
      By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, and Jade Rubick.
    </para>
</authorblurb>
  <sect2 id="using-cvs-with-openacs">
    <title>Using CVS with OpenACS</title>
    <sect3>
      <title>Getting Started</title>
      <para>
        All OpenACS code is available anonymously.  To get code
      anonymously, use the parameter
      <computeroutput>-d:pserver:anonymous@cvs.openacs.org:/cvsroot</computeroutput> immediately after <computeroutput>cvs</computeroutput> in a cvs command to check out or export code.
      </para>
      <para>
        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
        <computeroutput>-d:ext:cvs.openacs.org:/cvsroot</computeroutput>
        immediately after <computeroutput>cvs</computeroutput> 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
        <computeroutput>:ext:foobar@cvs.openacs.org:/cvsroot</computeroutput>.  The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts.
      </para>
      
      <para>
        OpenACS.org supports non-anonymous cvs access only over ssh, so you
        must have <computeroutput>CVS_RSH=ssh</computeroutput> in your
        environment.  (Typically this is accomplished by putting
        <computeroutput>export CVS_RSH=ssh</computeroutput> into
        <computeroutput>~/.bash_profile</computeroutput>.).  If your local
        account name does not match your cvs.openacs.org account name, create a
        file <computeroutput>~/.ssh/config</computeroutput> with an entry
        like:
      </para>
      <programlisting>Host cvs.openacs.org
    User joel
</programlisting>
      <para>
        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.  (<ulink
        url="http://www.uberdose.com/kbase/ssh-automatic-login/">More
        information</ulink>)
      </para>

      <para>
        You may want to set some more default actions for CVS usage.
  To do so, create the file
        <computeroutput>~/.cvsrc</computeroutput> with the contents:
      </para>
      <screen><action>cvs -z6
cvs -q</action></screen>
      <para><computeroutput>-z6</computeroutput> speeds up cvs access over the network quite a bit by enabling compressed
        connection by default.  <computeroutput>-q</computeroutput> suppresses some verbose output from commands.  For example, it makes the output of <computeroutput>cvs up</computeroutput> much easier to read.</para>
      <sidebar>
        <para>Administrator Note: These are the steps to grant CVS commit rights to a user:</para>
      <orderedlist>
        <listitem>
          <para>Create the user's account.  On cvs.openacs.org:</para>
          <screen><action>sudo bash
/usr/sbin/useradd -c "<replaceable>Real Name</replaceable>" -G cvs -p <replaceable>passwd</replaceable> <replaceable>username</replaceable>
/usr/sbin/usermod -G cvs,<replaceable>username</replaceable> <replaceable>username</replaceable>
          </action></screen>
        </listitem>
        <listitem>
          <para>Grant cvs access to the user account.  On any machine, in a temporary directory:</para>
          <screen><action>cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
cd CVSROOT
emacs avail</action></screen>
          <para>Add an avail line of the form:</para>
          <programlisting>avail|<replaceable>username</replaceable>|openacs-4</programlisting>
          <screen><action>cvs commit -m "added commit on X for username" avail</action></screen>
        </listitem>
      </orderedlist>
      </sidebar>
      <sidebar>
        <para>Branimir suggests an additional level of abstraction.  If you put</para>
        <programlisting>Host cvs-server
      HostName cvs.openacs.org
      User <replaceable>yournamehere</replaceable></programlisting>
        <para>into your <computeroutput>~/.ssh/config</computeroutput> file, then you can use <computeroutput>-d :ext:cvs-server:/cvsroot</computeroutput> instead of <computeroutput>-d :ext:cvs.openacs.org:/cvsroot</computeroutput>.  You can then change the definition of <computeroutput>cvs-server</computeroutput> by changing one file instead of editing hundreds of <computeroutput>CVSROOT/Repository</computeroutput> files.</para>
      </sidebar>

    </sect3>

    <sect3>
      <title>Checkout for Package Development</title>
      <para>If you are actively developing a non-core package, you
      should work from the latest core release branch.  Currently this
      is &releasebranch;.  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,</para>
      <screen><action>cvs -d :ext:cvs.openacs.org:/cvsroot co -r &releasebranch; openacs-4</action></screen>
      <para>If you work in the directories created with this command, all of your
            cvs updates and commits will be confined to the &releasebranch;
            branch.  Your work will be merged back to HEAD for you
            with each release.</para>
            
      <para>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:</para>
      <screen><action>cvs -d:ext:cvs.openacs.org:/cvsroot -r &releasebranch; checkout acs-core</action></screen>
      <para>Then add modules as needed:</para>
      <screen><action>cd /var/lib/aolserver/<replaceable>service0</replaceable>/packages
cvs up -d <replaceable>packagename</replaceable></action></screen>

      <para>... where <replaceable>packagename</replaceable> is the
            name of the package you want. Visit the <ulink
            url="http://openacs.org/packages"> Package
            Inventory</ulink> and <ulink
            url="http://openacs.org/projects/openacs/packages/">Package
            maintainers and status</ulink> for a list of available
            packages and their current state.
      </para>
    </sect3>

    <sect3>
      <title>Checkout for Core Development</title>
      <para>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
              <computeroutput>-r</computeroutput> tag.</para>
      <para></para>
      <para>To check out HEAD for development, which requires an OpenACS developer account:</para>
      <screen><action>cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</action></screen>
      <para>To check out HEAD anonymously:</para>
      <screen><action>cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core</action></screen>
    </sect3>

    <sect3>
      <title>Checkout .LRN</title>
      <para>
        .LRN consists of a given version openacs core, plus a set of
        packages. These are collectively packages together to form a
        distrubution 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
        <literal>dotlrn</literal>:
      </para>
      <screen><action>cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r &releasebranch; acs-core
mv openacs-4 dotlrn
cd dotlrn/packages
cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r &releasebranch; dotlrn-all
mv dotlrn/install.xml ..</action></screen>
    </sect3>
  <sect3 id="working-with-cvs">
    <title>Working with CVS</title>
    <para>
      Once you have a checkout you can use some commands to track
      what has changed since you checked out your copy.  <computeroutput>cvs -n update</computeroutput> does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS.
    </para>
    <para>To update your files, use <computeroutput>cvs update</computeroutput>.  This will merge changes from the repository with your local files.  It has no effect on the cvs.openacs.org repository.</para>
    </sect3>
  </sect2>

  <sect2 id="openacs-cvs-concepts">
    <title>OpenACS CVS Concepts</title>
    <sect3>
      <title>Modules</title>
      <para>
        All OpenACS code resides within a single CVS module, <computeroutput>openacs-4</computeroutput>.  (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 <computeroutput>openacs-4</computeroutput> are repackaged as smaller modules.</para>
        
        <para>
          <computeroutput>acs-core</computeroutput> 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.
        </para>
      <para>The complete list of core packages is:</para>
<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</programlisting>

        <para>
          <computeroutput>dotlrn-all</computeroutput> contains the packages required, in combination with acs-core, to run the .LRN system.
        </para>

        <para>
          <computeroutput>project-manager-all</computeroutput> contains the packages required, in combination with acs-core, to run the project-manager package.
        </para>

        <para>
          Each OpenACS package (i.e., directory in <computeroutput>openacs-4/packages/</computeroutput>) is also aliased as a module of the same name.
        </para>

    </sect3>

    <sect3>
      <title>
        Tags and Branches
      </title>
      <para>
        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. </para>
            <itemizedlist>
              <listitem>
            <para><computeroutput>openacs-<replaceable>x</replaceable>-<replaceable>y</replaceable>-<replaceable>z</replaceable>-final</computeroutput>
            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: <computeroutput>openacs-5-0-4-final</computeroutput>.
                </para>
              </listitem>
              <listitem>
            <para><computeroutput>dotlrn-<replaceable>x</replaceable>-<replaceable>y</replaceable>-<replaceable>z</replaceable>-final</computeroutput>
            tags mark final releases of .LRN.  These tags apply only to .LRN packages.  Example: <computeroutput>dotlrn-2-0-1-final</computeroutput>
                </para>
              </listitem>
              <listitem>
            <para><computeroutput><replaceable>packagename</replaceable>-<replaceable>x</replaceable>-<replaceable>y</replaceable>-<replaceable>z</replaceable>-final</computeroutput>
                  tags apply to releases of individual packages.  For example, <computeroutput>calendar-2-0-0-final</computeroutput> 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.
                </para>
              </listitem>

              <listitem>
            <para><computeroutput>openacs-<replaceable>x</replaceable>-<replaceable>y</replaceable>-compat</computeroutput> tags point to the most recent released version of OpenACS <replaceable>X</replaceable>.<replaceable>Y</replaceable>.
            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. 
            </para>
            <para>
              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.
            </para>
              </listitem>
              <listitem>
                <para>oacs-<replaceable>x</replaceable>-<replaceable>y</replaceable> is a <emphasis>branch, </emphasis>, 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.</para>
                <para>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.</para>
              </listitem>
        <listitem>
          <para><computeroutput>HEAD</computeroutput> is a branch used
          for development of core packages.</para>
        </listitem>
      </itemizedlist>
    </sect3>
  </sect2>

  <sect2 id="contributing-code">
    <title>Contributing code back to OpenACS</title>
    <para>There are three main ways to contribute code to OpenACS:</para>
    <orderedlist>
      <listitem>
        <para>To contribute a small fix, if you do not have a developer account, submit a <ulink url="http://openacs.org/bugtracker/openacs/patch-submission-instructions.htm">patch</ulink>.</para>
      </listitem>
      <listitem>
        <para>If you are making many changes, or would like to become a direct contributor, send mail to <ulink url="mailto:oct@openacs.org">the Core Team</ulink> asking for commit rights.  You can then commit code directly to the repository:</para>
      <orderedlist>
        <listitem>
          <para>Use one of the checkout methods described above to get files to your system.  This takes the place of steps 1 and 2 in <xref linkend="install-from-tarball"/>.  Continue setting up the site as described there.</para>
        </listitem>
        <listitem>
          <para>Fix bugs and add features.</para>
        </listitem>
        <listitem>
          <para>
            Commit that file (or files): </para>
            <screen><action>cvs commit -m "what I did and why" filename</action></screen>
          <para>
            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.
          </para>
        </listitem>
              <listitem>
                <para>
                  Confirm via the <ulink url="http://cvs.openacs.org/cvs/openacs-4/">
                    OpenACS CVS browser </ulink>
                  that your changes are where you intended them to be.
                </para>
              </listitem>
      </orderedlist>
      </listitem>
      <listitem>
        <para>Add a new package.  Contact the <ulink url="mailto:oct@openacs.org">Core Team</ulink> to get approval and to get a module alias created.</para>
          <orderedlist>
            <listitem>
              <para>
                Check out acs-core on the HEAD branch.  (Weird things happen if you add files to a branch but not to HEAD):</para>
            <screen><action>cd /tmp
cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core</action></screen>
            <para>Copy your package directory from your working directory to this directory.  Make sure not to copy any CVS directories.</para>
            <screen><action>cp -r /var/lib/aolserver/<replaceable>service0</replaceable>/packages/<replaceable>newpackage</replaceable> /tmp/openacs-4/packages</action></screen>
            <para>Import the package into the cvs.openacs.org cvs repository:</para>
            <screen><action>cd /tmp/openacs-4/packages/<replaceable>newpackage</replaceable>
cvs import -m "Initial import of <replaceable>newpackage</replaceable>" openacs-4/packages/newpackage <replaceable>myname</replaceable> <replaceable>newpackage-0-1d</replaceable></action></screen>
            </listitem>
            <listitem>
              <para>Add the new package to the modules file. (An administrator has to do this step.)  On any machine, in a temporary directory:</para>
          <screen><action>cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
cd CVSROOT
emacs modules</action></screen>
          <para>Add a line of the form:</para>
              <programlisting><replaceable>photo-album-portlet</replaceable> openacs-4/packages/<replaceable>photo-album-portlet</replaceable></programlisting>
              <para>Commit the change:</para>
              <screen><action>cvs commit -m "added alias for package <replaceable>newpackage</replaceable>" modules</action></screen>
              <para>This should print something like:</para>
              <literallayout>cvs commit: Examining .
**** Access allowed: Personal Karma exceeds Environmental Karma.
Checking in modules;
/cvsroot/CVSROOT/modules,v  &lt;--  modules
new revision: 1.94; previous revision: 1.93
done
cvs commit: Rebuilding administrative file database</literallayout>
            </listitem>
          <listitem>
            <para>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:</para>
            <programlisting>cd /var/lib/aolserver/<replaceable>service0</replaceable>/packages/<replaceable>newpackage</replaceable>
cvs tag -b <replaceable>oacs-5-1</replaceable></programlisting>
          </listitem>
          <listitem>
            <para>See <xref linkend="releasing-package"/></para>
          </listitem>
          </orderedlist>
        <note>
          <para>Some packages are already in cvs at <computeroutput>openacs-4/contrib/packages</computeroutput>.  Starting with OpenACS 5.1, we have a Maturity mechanism in the APM which makes the <computeroutput>contrib</computeroutput> directory un-necessary.  If you are working on a <computeroutput>contrib</computeroutput> package, you should move it to <computeroutput>/packages</computeroutput>.  This must be done by an OpenACS administrator.  On cvs.openacs.org:</para>
          <orderedlist>
            <listitem>
              <programlisting>cp -r /cvsroot/openacs-4/contrib/packages/<replaceable>package0</replaceable> /cvsroot/openacs-4/packages</programlisting>
            </listitem>
            <listitem>
              <para>Update the modules file as described above.</para>
            </listitem>
            <listitem>
              <para>Remove the directory from cvs in the old location using <computeroutput>cvs rm</computeroutput>.  One approach <computeroutput>for file in `find | grep -v CVS`; do rm $file; cvs remove $file; done</computeroutput></para>
            </listitem>
          </orderedlist>
        </note>
      </listitem>
    </orderedlist>

  <sect3 id="Commit_Rules">
    <title>
      Rules for Committing Code to the OpenACS repository
    </title>
    <para>
      CVS commit procedures are governed by 
      <ulink url="http://openacs.org/forums/message-view?message_id=185506">
        TIP (Technical Improvement Proposal) #61: Guidelines for CVS committers
      </ulink>
    </para>
    <orderedlist>

      <listitem>
        <para>
          Which branch?
        </para>

        <orderedlist numeration="arabic">

          <listitem>
            <para>
              For core packages, new features should always be
              committed on HEAD, not to release branches.
            </para>
          </listitem>

          <listitem>
            <para>
              For core packages, bug fixes should be committed on the
              current release branch whenever applicable.
            </para>
          </listitem>

          <listitem>
            <para>
              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.
            </para>
            <para>
              <emphasis>
                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.</emphasis></para>
          </listitem>

          <listitem>
            <para>
              The current release branch is merged back to HEAD after
              each dot release.
            </para>
          </listitem>
        </orderedlist>
      </listitem>
      
      <listitem>
        <para>
          New packages should be created in the 
          <computeroutput>
            /packages
          </computeroutput>
          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)
        </para>
      </listitem>

      <listitem>
        <para>
          Code
        </para>
        <orderedlist numeration="arabic">
          <listitem>
            <para>
              Only GPL code and material should be committed to the
              OpenACS CVS repository (cvs.openacs.org)
            </para>
          </listitem>
          <listitem>
            <para>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.  <emphasis>Reason: This makes auditing and merging code much easier.</emphasis>
            </para>
          </listitem>
          <listitem>
            <para>
              Database upgrade scripts should only span one release
              increment, and should follow
              <ulink url="http://openacs.org/doc/current/eng-standards-versioning.html#naming-upgrade-scripts">
                Naming Database Upgrade Scripts
              </ulink>
              .
            </para>
            <para>
              <emphasis>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.</emphasis>
      </para>

          </listitem>
          <listitem>
            <para>
              Database upgrade scripts should never go to the release
              version, e.g., should always have a letter suffix such as d1 or
              b1.
            </para>
          </listitem>
          <listitem>
            <para>
              CVS commit messages should be intelligible in the context
              of Changelogs. They should not refer to the files or
              versions.
            </para>
          </listitem>
          <listitem>
            <para>
              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
              ...".
            </para>
          </listitem>
        </orderedlist>
      </listitem>

      <listitem>
        <para>
          When to TIP
        </para>
        <orderedlist numeration="arabic">
          <listitem>
            <para>
              A TIP is a Techical Improvement Proposal (
              <ulink url="http://openacs.org/forums/message-view?message_id=115576">
                more information
              </ulink>
              ).  A proposed change must be approved by TIP if:
            </para>
            <orderedlist numeration="arabic">
          <listitem>
            <para>
              It changes the core data model, or
            </para>
          </listitem>
          <listitem>
            <para>
              It will change the behavior of any core package in a way
              that affects existing code (typically, by changing public API), or
            </para>
          </listitem>
          <listitem>
            <para>
              It is a non-backwards-compatible change to any core or
              standard package.
            </para>
          </listitem>
        </orderedlist>
          </listitem>
          <listitem>
            <para>
          A proposed change need not be TIPped if:
        </para>
        <orderedlist numeration="arabic">
          <listitem>
            <para>
              it adds a new function to a core package in a way that:
            </para>
            <orderedlist numeration="arabic">
              <listitem>
                <para>
                  does not change the backwards-compatibility of public API
                  functions.
                </para>
              </listitem>
              <listitem>
                <para>
                  does not change the data model
                </para>
              </listitem>
              <listitem>
                <para>
                  has no negative impact on performance
                </para>
              </listitem>
            </orderedlist>
          </listitem>
          <listitem>
            <para>
              it changes private API, or
            </para>
          </listitem>
          <listitem>
            <para>
              it is a change to a non-core, non-standard package
            </para>
          </listitem>
            </orderedlist>
          </listitem>
        </orderedlist>
      </listitem>
      <listitem>
        <para>
          Tags
        </para>
        <orderedlist numeration="arabic">
          <listitem>
            <para>
              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.
            </para>
      <para>
        <emphasis>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.</emphasis>
      </para>
          </listitem>
          <listitem>
            <para>
              When OpenACS core is released, the openacs-x-y-z-final
              tag shall be applied to all compat packages.
            </para>
      <para>
        <emphasis>
        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.
        </emphasis>
      </para>
          </listitem>
        </orderedlist>
        <para>
          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.
        </para>
      </listitem>
    </orderedlist>
  </sect3>
  <sect3>
    <title>
      Informal Guidelines
    </title>
    <para>
      Informal guidelines which may be obsolete in places and should be reviewed:
    </para>
    <itemizedlist>
      <listitem>
        <para>
          Before committing to cvs you must submit a bug report and
          patch to the 
          <ulink url="http://openacs.org/bugtracker/openacs">
            OpenACS
            bug tracker
          </ulink>
          . The only exceptions to this rule are
          for 
          <ulink url="/projects/openacs/4.7/package_inventory">
            package
            maintainers
          </ulink>
          committing in a package they are
          maintaining and for members of the core team.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
      <listitem>
        <para>
          If you are changing the data model you *must* provide an
          upgrade script and bump up the version number of the
          package.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
      <listitem>
        <para>
          Never rush to commit something. Before committing double
          check with cvs diff what exactly you are committing.
        </para>
      </listitem>
      <listitem>
        <para>
          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".
        </para>
      </listitem>
      <listitem>
        <para>
          Commit one cohesive bug fix or feature change at a time.
          Don't put a bunch of unrelated changes into one commit.
        </para>
      </listitem>
      <listitem>
        <para>
          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.
        </para>
      </listitem>
      <listitem>
        <para>
          Test your change before committing. Use the OpenACS
          package acs-automated-testing to test Tcl procedures and the tool
          
          <ulink url="http://tclwebtest.sourceforge.net">
            Tclwebtest
          </ulink>

          to test pages
        </para>
      </listitem>

      <listitem>
        <para>
          Keep code simple, adhere to conventions, and use comments
          liberally.
        </para>
      </listitem>

      <listitem>
        <para>
          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.
        </para>
      </listitem>

    </itemizedlist>
  </sect3>
  </sect2>
  <sect2 id="cvs-resources">
    <title>Additional Resources for CVS</title>
    <itemizedlist>
      <listitem>
        <para>
          The 
            <ulink url="http://cvs.openacs.org/cvs/">
              OpenACS cvs web</ulink>
            and
            <ulink url="http://xarg.net/tools/cvs/">
              Jeff's cvs
              browser
            </ulink>
            are useful tools in understanding what is
            happening with the code.
          </para>
        </listitem>
        <listitem>
          <para>
            There is a mailing list of cvs changes at
      <ulink url="http://willfork.com/mailman/listinfo/openacs-cvs-list">
        willfork.com
      </ulink>
          </para>
        </listitem>
        <listitem>
          <para>There is an RSS feed of cvs changes at 
          <ulink url="http://xarg.net/tools/cvs/rss/?days=3">
            RSS feed
          </ulink>
          </para>
        </listitem>

        
        <listitem>
          <para>
            <ulink url="https://www.cvshome.org/docs/manual/cvs-1.11.17/cvs.html">cvs manual</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="https://www.cvshome.org/docs/manual/cvs-1.11.17/cvs_7.html#SEC66">adding files/dirs with cvs</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="https://www.cvshome.org/docs/manual/cvs-1.11.17/cvs_10.html#SEC82">file locking etc. with cvs</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="http://www.piskorski.com/docs/cvs-conventions.html">Piskorski's cvs refs</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="http://openacs.org/doc/current/backups-with-cvs.html">backup with cvs</ulink>
          </para>
        </listitem>
        <listitem>
          <para>
            <ulink url="http://openacs.org/forums/message-view?message_id=178551">merging 2 file heirarchies with cvs</ulink>
          </para>
        </listitem>
      </itemizedlist>


  </sect2>
  
</sect1>


