root/swish-e/branches/rel-2-4-0-patches/swish-e/README.cvs

Using CVS
---------

Swish-e is available via cvs from SourceForge.  See http://swish-e.org for 
links to SourceForge and instructions downloading via cvs.

Much of the documentation is not stored in cvs, but rather built from source 
files (mostly .pod files in the pod directory). 

Documentation is built with Perl code that's part of the swish-e 
distribution.  Still, your system may not have the required tools for this 
operation.  If that is the case you can disable much of the documentation 
building by building with:

  ./configure --disable-docs
  make
  make check
  make install

Developer Notes:

Release and Tag
---------------

1) Run cvs update to make sure have current sources and cvs -nq update to 
   make sure there's nothing left to check in

2) Edit the pod/CHANGES.pod file to update the date of the release

3) Edit the version in configure.in

4) run ./bootstrap to create new makefile.in with new version string

5) run make distcheck to make sure it all builds correctly.  This will also
   update the HTML documentation (since CHANGES.pod is newer).  This is
   IMPORTANT because if the HTML docs are out of date then make on users
   systems will attempt to build the documentation and they may not have the
   right tools installed.

6) good idea to upload the tarball created by make distcheck someplace and 
   then test on a few platforms

7)  Check in the updated version Makefiles:  

  $ cvs ci

8) Tag the release.  For example:

   $ cvs tag rel-2-4-0

9) Upload to swish-e site -- see README on swish-e site for details.

Now move on to development.  Change version in configure.in (2.5.0 for example),
run ./bootstrap and check in.


Patching a previous version
---------------------------

Say development has started on the next release but a bug is found in the last. 
Development has gone on too far to use the development version.

-- Creating a Branch in CVS -

The first thing that is needed is to create a branch of the cvs tree.  This 
only needs to be done *once*, and there's more than one way to do it: you can 
either branch based on a checked out version (e.g. first check out the tagged 
version), or the branch can be done on the repository.

So, to just branch the repository:

  $ cvs -d :ext:<developer>@cvs.sourceforge.net:/cvsroot/swishe rtag -b -r rel-2-4-0 rel-2-4-0-patches swish-e

which says to create a branch called rel-2-4-0.patches branched off of the 
tagged source rel-2-4-0.

[See NOTE below about before following this example]

-- Checkout branch --

Again, two ways to go here.  You can convert your existing local source tree
to the branch or simply do a new checkout.  I prefer to do a new checkout.

  $ cvs -d :ext:<moseley>@cvs.sourceforge.net:/cvsroot/swishe -z3 checkout -r rel-2-4-0-patches -d swish-e-2.4.0.patches swish-e

This specifies the Root again with -d, -z3 is compression, we checkout 
rel-2-4-0-patches from the swish-e module, but instead of writing to
the "swish-e" directory use -d to create a directory called 
swish-e-2.4.0.patches swish-e.

-- Make chages --

Make changes as normal.  Check in as normal:

  $ cvs ci

and that will ONLY update this current branch.


-- Merging changes back to main branch --

Changes and fixes that are done on the branch will proably need to be moved
to the main branch.

To merge in changs from another branch into your working copy (the main HEAD 
branch - 2.5.x in this example)

  (in your 2.5.x working copy)
  $ cvs -j rel-2-4-0-patches

That should update your sources.  Watch out for conflicts!

Note that this is a bit tricky, because this will likely change the version 
number in configure.in.

Verify version in configure.in (might have been changed) then don't forget to 
check the new patches into the HEAD branch.

  $ cvs ci -m "Merged patches from 2-4-0-patches" 

Now, once merged go to your patches directory (swish-e-2.4.0.patches in this 
example) and *tag* it.  That will allow merging later updates into the HEAD 
branch without re-merging what was just merged.

  (in the .patches directory)
  $ cvs tag rel-2-4-1

that just tags the rel-2-4-0-patches branch.

Then when 2.4.2 is later created, just the changes from 2.4.1 to 2.4.2 can be 
merged:

  (in the main branch)
  $ cvs update -j rel-2-4-1 -j rel-2-4-0-patches

which says merge from the tag rel-2-4-1 to the end of the branch 
rel-2-4-0-patches into the current directory.

At least I think that's how it works.


NOTE: The example for naming the branch may not be best.  In this example we 
are fixing a bug in 2.4.0 so will likely release a 2.4.1.  Development is now 
in 2.5.x.  So it may be better to create the branch as rel-2-4-patches (instead 
of rel-2-4-0-patches) and then all 2.4.x updates will get added there.