A crash course in Yacas maintenance for developers

This document intends to give a concise description of the way
Yacas is maintained. There are a few parts to maintenance to
take into account:

*	The {autoconf}/{automake} part -- makefile maintenance over various systems.
*	The {cvs} system -- enabling developers to work together.
*	The back up repository -- storage of tarballs with versions of Yacas.
This can be found at the following address:

<*http://www.xs4all.nl/~apinkus/backups/*>

	    The {autoconf}/{automake} system

*A build system
The short story is as follows. You probably do not need to bother about this
unless you introduce a new file. However, if you add a new file, it probably
should be added to the {Makefile.am} file in the same directory. In many
cases, it should be clear from the {Makefile.am} file where your new file
should be added. For instance, new Yacas script files go into the huge list
in {scripts/Makefile.am} that is assigned to the {SCRIPTFILES} variable.
Similarly, test scripts should go in the list in {tests/Makefile.am} that is
assigned to the {TESTFILES} variable. Note that you should probably also run
the {cvs add} command, as explained in the section on CVS below. If you remove
a file, then you should go through the inverse procedure.

The addition of new files to the {Makefile.am} ensures that it will be added
to the tarball {yacas-*.tar.gz} which is uploaded to the backup repository.
This has the nice side effect that you can have local files which don't
automatically get added to the distribution (by not adding them to the
{Makefile.am} file). Additionally, files which are not listed in {Makefile.am}
may not be built and/or installed automatically.  To make sure that the
{tar.gz} distribution is complete, you can run the command
	make distcheck
This may take a little while, as it needs to rebuild and test the whole system
from the {tar.gz} tarball.

If you want to do more complicated things (like adding files which are not
Yacas script or test files, or files which should be compiled or installed
only conditionally), or if you are simply curious, you can read more in the
chapter entitled "The Yacas build system".


	    Maintaining Yacas through a {cvs} repository

*A CVS
{CVS} provides an efficient way for developers to work together, automatically
merging changes various developers make, and at the same tile is a back up 
system (uploading your changes to another computer from which you can
easily obtain it at a later time). After a little effort setting it
up it becomes very easy to use. This section describes the few commands
needed for keeping your version and the version in the Yacas repository
up to date.

	    How does {cvs} work?

CVS has a copy of the files in the repository somewhere in a directory
on some system, possibly your computer. Then there is such a thing
as a cvs server which you can talk to to synchronize your version of
the source code with the version on the server. 

CVS uses a diff-like scheme for merging differences: it looks at two
text files, determines the different lines, and merges accordingly.
It discovers the changes you made by looking at the version you checked
out last and the version you have now, to discover which lines changed
(it maintains an automatic version number for each file).

If the version of a file on your system and the version in the
cvs repository has a line that has been changed by both you and some 
one else, the cvs repository will obviously not know what to do with that,
and it will signal a 'collision' which you will have to solve by hand
(don't worry, this rarely happens). More on that later.

In commands to be described in this document are in short: 

*	{cvs checkout} will get you an initial version. You only need to call this once.
*	{cvs update} will merge the two versions and put it on your computer, so you have the latest version.
*	{cvs commit} will merge the two versions and put it in the cvs repository.
*	{cvs add} to add a file or directory.
*	{cvs remove} to remove a file.

	    Checking out an initial version of Yacas

*A CVS!check out
There are two ways to check out a version of Yacas: as anonymous 
user and as maintainer. Anonymous users don't need to log in,
but also have no right to commit changes. Maintainers first need
to get an account (at sourceforge), and their account needs to 
be enabled so they are allowed by the maintainer to make changes.
A maintainer needs to log in with every command. To be able to
log in, you need ssh1 installed (ssh2 will not work). You can 
find this at http://www.ssh.org/download.html.


To check out Yacas as anonymous user, type:

	cvs -d:pserver:anonymous@yacas.cvs.
	  sourceforge.net:/cvsroot/yacas login
	cvs -z3 -d:pserver:anonymous@yacas.cvs.
	  sourceforge.net:/cvsroot/yacas co yacas

To check out as a maintainer, type:

	export CVS_RSH=ssh1

This will tell CVS to use ssh1 for communication. Then, in order to download the yacas source tree, type

	cvs -d:ext:loginname@yacas.cvs.sourceforge.
	  net:/cvsroot/yacas co yacas
where {loginname} is your name on the sourceforge system.
This creates a directory {yacas/} with the full most recent distribution.
You need to enter your password there, but other than that, that's it!

Those lines typed above are long and obscure, but it is also
the last time you need to type them. From now on, if you want to do 
anything with cvs, just go into the {yacas/} directory you just checked
out, and type the cvs command without the {-d:}... flag. This flag
just tells cvs where to find the repository. But future cvs commands
will know where to find them, which is why you don't need that flag.

	    Use case scenario 1 : getting the latest version of Yacas

*A CVS!update
You haven't looked at Yacas for a while (shame on you!) and want 
to check out the latest version. Just type

	cvs update -d

on the command line in the {yacas} directory, and that should essentially
download the latest version for you in that directory (just the changes).
The {-d} option here states that you are also interested in new directories
that were added to the repository. Oddly enough, cvs will only get
you changed and added files, not added directories, by default.

A command

	cvs -q update -d

will print messages only about changed files.

	    Use case scenario 2 : you made changes to Yacas

*A CVS!commit
You got the latest version, but saw this huge, glaring omission in
Yacas, and start hacking away to add it yourself. After a while, 
after playing with the code you wrote, and if you think you are
finished with it, you decide you like to add it to the cvs repository.

First, you should test the new Yacas system:
	make test
If there are any failed tests, you need to fix them.

Now you can start entering your changes to the CVS. If you created some new files, you need to tell CVS to add them to the source tree:

{cvs add } [list of file names of ascii text files]

This adds ascii text files. If you added binary files (GIF images
in the documentation directory, or something like that), you can 
add it to the CVS with 

{cvs add -kb } [list of file names of binary files]

Note that, when adding files to the CVS, you should normally also add them to
the Yacas {tar.gz} distribution. This is done by adding the file name to the {EXTRA_DIST}
variable in the file {Makefile.am} in the directory where you were adding the file.

In case files need to be removed, there are two options:

*	The file is still on your drive: call {cvs remove -f [filename]} to remove
the file from both your computer and the cvs repository.
*	You already removed the file from your system: call {cvs remove [filename]}

There seems to be no easy way to rename or move files; you would have to remove them at their old location and add them at a new location.

Now, when finished with that, you might want to 'commit' all
changes with

	cvs commit

If the commit succeeds, an email is sent out to the maintainers,
who can then scan the diff files for changes, to see if they
agree with the changes, and perhaps fix mistakes made (if any).

If there is a collision, the commit fails (it will tell you so). 
This might happen because someone else also edited the same place in a file and their changes cannot be automatically merged with yours.
In case of a collision, you need to invoke {cvs update} twice.
The {cvs update} outputs a list of file names with a character
in front of them. The important ones are the files with a 'C' before
them. They have a collision. You can go into the file, and see the
collision, which the cvs system conveniently marks as:

	<<<<<<
	old version
	===========
	new version
	>>>>>>

You can edit the file by merging the two versions by hand. This
happens very rarely, but it can happen. Use {cvs commit} afterwards
to commit.

The {commit} and {update} commands can be performed in specific 
directories, and on specific files, if necessary, by stating them
on the command line. Or you can go into a sub directory and do a
{cvs commit} or {cvs update} there, if you are confident that is
the only place that changed or whose changes you are interested in.

That is basically it, a quick crash course cvs. It is actually very
convenient in that usually all that is needed is a {cvs commit}
to fix small bugs. You type that in, and your version gets merged
with the changes others made, and they get your changes, and you 
backed up your changes at the same time (all with that little command!).

You can find more information about cvs at <*http://cvsbook.red-bean.com/*>.