Index: openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp =================================================================== RCS file: /usr/local/cvsroot/openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp,v diff -u -r1.5 -r1.6 --- openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp 25 Apr 2018 08:38:27 -0000 1.5 +++ openacs-4/packages/acs-core-docs/www/cvs-guidelines.adp 3 Sep 2024 15:37:31 -0000 1.6 @@ -1,23 +1,29 @@ -{/doc/acs-core-docs {ACS Core Documentation}} {CVS Guidelines} +{/doc/acs-core-docs/ {ACS Core Documentation}} {CVS Guidelines} CVS Guidelines +

- CVS Guidelines

<authorblurb>

($‌Id: cvs.xml,v -1.8 2018/03/27 11:18:00 hectorr Exp $)

By Joel Aufrecht with input from Jeff Davis, Branimir Dolicki, + CVS Guidelines

+
($‌Id: cvs.xml,v 1.9.2.2 2022/10/19 09:29:50 +gustafn Exp $)

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

-</authorblurb> -
+OpenACS docs are written by the named authors, and may be edited by +OpenACS documentation staff.

Using CVS with OpenACS

-Getting Started

All OpenACS code is available anonymously. To get code +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.

If you are an OpenACS developer, you should check out code so @@ -42,8 +48,8 @@ cvs command. To avoid this, set up ssh certificate authentication for your OpenACS account. (More information)

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

cvs -z6
-cvs -q

+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 @@ -52,22 +58,21 @@

Administrator Note: These are the steps to grant CVS commit rights to a user:

  1. -

    Create the user's account. On cvs.openacs.org:

    sudo bash
-/usr/sbin/useradd -c "Real Name" -G cvs -p passwdusername
-/usr/sbin/usermod -G cvs,usernameusername
-
    +

    Create the user's account. On cvs.openacs.org:

    sudo bash
+adduser --add_extra_groups cvs --gecos "Real Name" --shell /bin/bash username
+

  2. Grant cvs access to the user account. On any machine, in a -temporary directory:

    cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
+temporary directory:
    cvs -d :ext:cvs.openacs.org:/cvsroot co CVSROOT
 cd CVSROOT
-emacs avail
    Add an avail line of the form:
    avail|username|openacs-4
    cvs commit -m "added commit on X for username" avail
    
+emacs avail

    Add an avail line of the form:

    avail|username|openacs-4
    cvs commit -m "added commit on X for username" avail

Branimir suggests an additional level of abstraction. If you put

Host cvs-server
       HostName cvs.openacs.org
-      User yournamehere
+      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 @@ -76,43 +81,46 @@

-Checkout for Package Development

If you are actively developing a non-core package, you should +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-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,

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

If you work in the directories created with this command, all of +non-core packages. To check out all packages,

cvs -d :ext:cvs.openacs.org:/cvsroot co -r oacs-5-9 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-9 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-9 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 +core first:

cvs -d:ext:cvs.openacs.org:/cvsroot -r oacs-5-9 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 Core, +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
+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 +Checkout +.LRN

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

cvs -d :pserver:anonymous\@cvs.openacs.org:/cvsroot checkout -r oacs-5-9 acs-core
+dotlrn:
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 ..

+mv dotlrn/install.xml ..

Working with CVS

Once you have a checkout you can use some commands to track what @@ -127,7 +135,7 @@

OpenACS CVS Concepts

-Modules

All OpenACS code resides within a single CVS module, +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 @@ -162,49 +170,55 @@ module of the same name.

- Tags and Branches

Tags and Branches look similar in commands, but behave + 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 +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.

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

    For example, if you check out the entire tree with -r +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 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.

    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.

  • -

    oacs-x-y is a branch, , 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.

    These branches are used for two purposes. OpenACS Core packages +

    oacs-x-y is a +branch, , 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.

    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 @@ -229,7 +243,7 @@ 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.

  • Fix bugs and add features.

  • -

    Commit that file (or files):

    cvs commit -m "what I did and why" filename

    Because this occurs in your personal checkout and not an +

    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 @@ -243,18 +257,18 @@ 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 mynamenewpackage-0-1d
-
      +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 mynamenewpackage-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
+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;
      @@ -267,8 +281,8 @@

      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
+branch your package:
      cd /var/lib/aolserver/service0/packages/newpackage
+cvs tag -b oacs-5-1

    3. See the section called “How to package and release an OpenACS Package” @@ -280,8 +294,7 @@ 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 +

      4. cp -r /cvsroot/openacs-4/contrib/packages/package0 /cvsroot/openacs-4/packages

      5. Update the modules file as described above.

      6. 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 @@ -301,7 +314,7 @@ HEAD, not to release branches.

      7. For core packages, bug fixes should be committed on the current release branch whenever applicable.

      8. For non-core packages, developers should work on a checkout of -the release branch of the lastest release. For example, if OpenACS +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.

        Reason: First, this ensures that @@ -345,7 +358,7 @@

      9. When to TIP

        1. -

          A TIP is a Techical Improvement Proposal ( more information ). A proposed change must be +

          A TIP is a Technical Improvement Proposal ( more information ). A proposed change must be approved by TIP if:

          1. It changes the core data model, or

          2. It will change the behavior of any core package in a way that affects existing code (typically, by changing public API), or

          3. It is a non-backwards-compatible change to any core or standard @@ -398,7 +411,8 @@

        - Informal Guidelines

        Informal guidelines which may be obsolete in places and should + Informal +Guidelines

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