Index: trunk/Ohana/doc/elixir-cvs.txt =================================================================== --- trunk/Ohana/doc/elixir-cvs.txt (revision 2632) +++ trunk/Ohana/doc/elixir-cvs.txt (revision 2792) @@ -54,2 +54,128 @@ Ohana scripts. I have modified sp_plot and el_plot to use 'dvo' instead. I have also modified elixir.photreport. + +--- + +Working with Elixir / Ohana and CVS: + +The CVS repositories allows the developer to work on a copy of the +Ohana software, make changes to their copy of the code, test the +changes within their own version of the Elixir configuration system, +share the changes with other developers, and freeze a tested, working +snapshot of portions of the software. + +The Ohana software tree is divided into packages, each possibly +containing a single program, a group of related programs, or a C +library. Within the Ohana software version control system, each of +these packages should be released as a single entity. Changes may be +made to any of the elements which make up the package. The new +changes should be tested so that the developer is confident that the +new version of the software may be safely introduced into the +production system. At this point, the entire package is tagged with +an identifying name and the new release of the package may be loaded +into the production tree. + +In the following discussion, we illustrate the process of creating a +new release of a package within Elixir. + +First, check out the Ohana tree: + +set CVSROOT to username@machine:/data/elixir2/srcdir/cvs where +'username' is your user ID and machine is one of the CFHT linux +machines which mount /data/elixir2/srcdir. + +check out your copy of the software tree: + + cvs co ohana + +you may also check out specific releases of packages with the command: + cvs co -r TAG PACKAGE eg: + cvs co -r libfits-1-0 libfits + +this version should be executed from the same directory level as the +cvs co ohana command; each package is placed in the directory +ohana/src/PACKAGE. + +The entire ohana package may be compiled from the ohana directory +with: + +> configure +> make +> make install + +Make edits, changes, etc to the programs in some package. For +example, you might edit the .c files in the directory +ohana/src/gastro/src. Occasionally publish your changes to the CVS +repository: + +cvs update (check for changes by other developers) +cvs commit [filename] (publish the changes) + +also: + +cvs add (filename) (add a new file to the repository). + +Once the changes have been made, make sure to compile and test your +copy of the program. If you are acting as a developer, you must have +your version of the ohana/bin/ARCH directory in your path (before the +production installation path, /apps/elixir/bin). Once the code has +been tested, and the package is ready for release, commit all of your +changes to the repository (cvs commit). Now you may tag the new +release of the package. Within the top-level directory of the +package, give the command: + +cvs tag -c TAG + +where TAG is the name of this release. Within the Ohana system, +packages are generally tagged with names of the form PACKAGE-N-M where +N and M are major and minor version numbers. For example, libfits has +tag names starting from libfits-1-0. If the changes are minor, and +don't affect interaction with other packages, then it is only +necessary to change the minor version number. If the new package +forces changes on other packages, it is best to change the major +version as well. Major version changes should be introduced only with +discussion among the affected parties! It is possible to check the +currenly assigned tags for a package with the command: +cvs status -v (filename) +where (filename) is some file that is part of the package. A +convenient file to use is the Makefile for the package. Assigning the +tag affects the repository directly (there is no need to run 'commit' +afterwards). If you have outstanding changes, the -c option will +force CVS to complain, so you will not tag different versions of the +files from what you expect. + +Once the tag has been assigned, the new version of the package may be +introduced to the production system. This is a two step process: +first the new source tree is placed in the appropriate location and +compiled. Then the new binaries are pushed to their final locations. +There are two options for installing the new package source code. +First, you may make a new elixir distribution. To do this, go into +the ohana/etc directory, and edit the distributions.txt file. This +defines the package releases which make up a complete distribution. +There are entries for the ohana/elixir distributions, mana +distributions, etc. Make a new distribution version, update the +appropriate package, and save the file. This distribution (or any +other older distribution) may now be constructed by executing the +command 'mkdist (distribution) (version)', for example: +mkdist elixir 1.0 +This command extracts from the CVS repository all of the package +versions which are specified to be part of the given distribution +version. These are placed in a single directory, along with the ohana +infrastructure pieces, with the directory name matching the package +name and version number. This new directory may be moved or copied to +the official production source code location +(/data/elixir2/srcdir/ohana). The entire tree may then be compiled. + +An alternative to the above is to checkout only the new package +version. To do this, go to the directory containing the production +code (ie, /data/elixir2/srcdir). Perform a checkout of the specific +tagged release of the package of interest: +cvs co -r TAG PACKAGE (ie, cvs co -r libfits-1-0 libfits). This will +replace the old version of the package with the new version. Now the +software may be recompiled from the ohana directory. + +Once a new version of the software has been compiled, it may be pushed +to the production binary directory. From the /data/elixir2/srcdir +directory, issue the command 'make install' (make install-test will +show what programs are new). +