Index: openacs-4/packages/acs-core-docs/www/cvs-guidelines.html =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-guidelines.html,v diff -u -r1.4 -r1.4.2.1 --- openacs-4/packages/acs-core-docs/www/cvs-guidelines.html 17 Jul 2006 05:38:31 -0000 1.4 +++ openacs-4/packages/acs-core-docs/www/cvs-guidelines.html 14 Jan 2007 04:20:10 -0000 1.4.2.1 @@ -1,36 +1,37 @@ + CVS Guidelines -

+

CVS Guidelines -

($Id$)

+

($Id$)

By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, and Jade Rubick.

OpenACS docs are written by the named authors, and may be edited by OpenACS documentation staff. -

Using CVS with OpenACS

Getting Started

+

Using CVS with OpenACS

Getting Started

All OpenACS code is available anonymously. To get code anonymously, use the parameter - -d:pserver:anonymous@cvs.openacs.org:/cvsroot immediately after cvs in a cvs command to check out or export code. + -d:pserver:anonymous@cvs.openacs.org:/cvsroot immediately after cvs in a cvs command to check out or export code.

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 - -d:ext:cvs.openacs.org:/cvsroot - immediately after cvs in + -d:ext:cvs.openacs.org:/cvsroot + immediately after cvs 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 + you are logged in as "foobar" it will try to check out and commit as if you had specified - :ext:foobar@cvs.openacs.org:/cvsroot. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts. + :ext:foobar@cvs.openacs.org:/cvsroot. The advantage of not specifying a user in the checkout command is that other users can work in the directory using their own accounts.

OpenACS.org supports non-anonymous cvs access only over ssh, so you - must have CVS_RSH=ssh in your + must have CVS_RSH=ssh in your environment. (Typically this is accomplished by putting - export CVS_RSH=ssh into - ~/.bash_profile.). If your local + export CVS_RSH=ssh into + ~/.bash_profile.). If your local account name does not match your cvs.openacs.org account name, create a - file ~/.ssh/config with an entry + file ~/.ssh/config with an entry like:

Host cvs.openacs.org
     User joel
@@ -42,55 +43,55 @@
       

You may want to set some more default actions for CVS usage. To do so, create the file - ~/.cvsrc with the contents: + ~/.cvsrc with the contents:

cvs -z6
-cvs -q

-z6 speeds up cvs access over the network quite a bit by enabling compressed - connection by default. -q suppresses some verbose output from commands. For example, it makes the output of cvs up much easier to read.

Checkout for Package Development

If you are actively developing a non-core package, you + User yournamehere

into your ~/.ssh/config file, then you can use -d :ext:cvs-server:/cvsroot instead of -d :ext:cvs.openacs.org:/cvsroot. You can then change the definition of cvs-server by changing one file instead of editing hundreds of CVSROOT/Repository files.

Checkout for Package Development

If you are actively developing a non-core package, you should work from the latest core release branch. Currently this - is oacs-5-2. This ensures that you are working on top + is oacs-5-3. 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,

cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-2 openacs-4

If you work in the directories created with this command, all of your - cvs updates and commits will be confined to the oacs-5-2 + changes to non-core packages. To check out all packages,

cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-3 openacs-4

If you work in the directories created with this command, all of your + cvs updates and commits will be confined to the oacs-5-3 branch. Your work will be merged back to HEAD for you with each release.

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:

cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-2 checkout acs-core

Then add modules as needed:

cd /var/lib/aolserver/service0/packages
+      this, check out core first:

cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-3 checkout acs-core

Then add modules as needed:

cd /var/lib/aolserver/service0/packages
 cvs up -d packagename

... where packagename is the name of the package you want. Visit the Package Inventory and Package maintainers and status for a list of available packages and their current state. -

Checkout for Core Development

If you are actively developing packages in the OpenACS +

Checkout for Core Development

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 - -r tag.

To check out HEAD for development, which requires an OpenACS developer account:

cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core

To check out HEAD anonymously:

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core

Checkout .LRN

+ -r tag.

To check out HEAD for development, which requires an OpenACS developer account:

cvs -d:ext:cvs.openacs.org:/cvsroot checkout acs-core

To check out HEAD anonymously:

cvs -d:pserver:anonymous@cvs.openacs.org:/cvsroot checkout acs-core

Checkout .LRN

.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 - dotlrn: -

cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-2 acs-core
+        dotlrn:
+      

cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-3 acs-core
 mv openacs-4 dotlrn
 cd dotlrn/packages
-cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-2 dotlrn-all
-mv dotlrn/install.xml ..

Working with CVS

+cvs -d :pserver:anonymous@cvs.openacs.org:/cvsroot checkout -r oacs-5-3 dotlrn-all +mv dotlrn/install.xml ..

Working with CVS

Once you have a checkout you can use some commands to track - what has changed since you checked out your copy. cvs -n update does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS. -

To update your files, use cvs update. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.

OpenACS CVS Concepts

Modules

- All OpenACS code resides within a single CVS module, openacs-4. (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 openacs-4 are repackaged as smaller modules.

- acs-core contains only critical common + what has changed since you checked out your copy. cvs -n update does not change any files, but reports which changes have been updated or locally modified, or are not present in CVS. +

To update your files, use cvs update. This will merge changes from the repository with your local files. It has no effect on the cvs.openacs.org repository.

OpenACS CVS Concepts

Modules

+ All OpenACS code resides within a single CVS module, openacs-4. (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 openacs-4 are repackaged as smaller modules.

+ acs-core 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. @@ -111,29 +112,29 @@ acs-tcl acs-templating ref-timezones search

- dotlrn-all contains the packages required, in combination with acs-core, to run the .LRN system. + dotlrn-all contains the packages required, in combination with acs-core, to run the .LRN system.

- project-manager-all contains the packages required, in combination with acs-core, to run the project-manager package. + project-manager-all contains the packages required, in combination with acs-core, to run the project-manager package.

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

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

Tags and Branches -

+

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.

  • openacs-x-y-z-final - 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: openacs-5-0-4-final. -

  • dotlrn-x-y-z-final - tags mark final releases of .LRN. These tags apply only to .LRN packages. Example: dotlrn-2-0-1-final -

  • packagename-x-y-z-final - tags apply to releases of individual packages. For example, calendar-2-0-0-final is a tag that will retrieve only the files in the calendar 2.0.0 release. It applies only to the + a branch if you will be working on the code.

    • openacs-x-y-z-final + 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: openacs-5-0-4-final. +

    • dotlrn-x-y-z-final + tags mark final releases of .LRN. These tags apply only to .LRN packages. Example: dotlrn-2-0-1-final +

    • packagename-x-y-z-final + tags apply to releases of individual packages. For example, calendar-2-0-0-final 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. -

    • openacs-x-y-compat tags point to the most recent released version of OpenACS X.Y. +

    • openacs-x-y-compat tags point to the most recent released version of OpenACS X.Y. 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 @@ -154,9 +155,9 @@ 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.

    • HEAD is a branch used - for development of core packages.

Contributing code back to OpenACS

There are three main ways to contribute code to OpenACS:

  1. To contribute a small fix, if you do not have a developer account, submit a patch.

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

      + 5.1, work on the oacs-5-0 branch.

    4. HEAD is a branch used + for development of core packages.

Contributing code back to OpenACS

There are three main ways to contribute code to OpenACS:

  1. To contribute a small fix, if you do not have a developer account, submit a patch.

  2. 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 Section�, “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. @@ -167,18 +168,18 @@

  3. 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
      +cvs import -m "Initial import of newpackage" openacs-4/packages/newpackage myname newpackage-0-1d
    3. 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�.
      +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

    4. 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
    5. 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

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 @@ -205,9 +206,9 @@ 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) @@ -243,11 +244,11 @@ versions.

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

    +

  • Informal Guidelines -

    +

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

    Additional Resources for CVS

    Additional Resources for CVS