Hello,
I'm sorry for the delay in opening the FreeMWare CVS tree, but unfortunately
there have been a few problems in getting the CVS set-up to work as expected ...
While still not everything is working quite as I'd like, we've now at least
the essential features running OK, so that we can start using CVS now.
To be able to access the complete development history, I've uploaded all
freemware releases up to now to the tree; you can use e.g. the CVSWEB access
to view diffs between the various versions. The head of the main CVS
branch is equivalent to the latest release (fmw-19990826a) with a few
fixes added so that it works with CVS (basically, CVS doesn't like to
store symbolic links ...).
I've put together a short text describing the set-up of the FreeMWare
CVS tree, and -for those not yet familiar with CVS- the essential features
of the CVS tool needed to access the tree. If there are any additional
questions or remarks, just let me know ...
The CVS access parameters and a description how to use CVS to download
the current tree should be added to the FreeMWare home page; furthermore
we'll need a link to the CVSWEB script ... (Wouter?)
Bye,
Ulrich
CVS ACCESS PARAMETERS:
For everyone already familiar with CVS, here's right away the access data
needed to use the FreeMWare CVS repository:
CVS Root: :pserver:[EMAIL PROTECTED]:/cvsroot-freemware
Password: <none>
Repository: freemware
CVS Web: http://www.freemware.org/cgi-bin/cvsweb.cgi
ANONYMOUS CVS ACCESS:
If you are *not* familiar with CVS, here's a step-by-step instruction how
to retrieve your initial copy of the FreeMWare CVS repository and how to
keep up to date:
First of all, you need to have the 'cvs' command. (On all Linux distros
I'm aware of, this is part of the distribution ...)
If you are accessing the FreeMWare CVS repository for the first time,
you need to log in to the CVS server:
cvs -d :pserver:[EMAIL PROTECTED]:/cvsroot-freemware login
The program will prompt for 'Password:'; as the password is empty, simply
hit return. [ If you do this twice, CVS won't ask for the password a second
time, as it stores the password within the ~/.cvspass file.]
Now, you can retrieve your initial copy of the repository. Go to the
directory where you want the copy to be created (the following command
will create a subdirectory 'freemware' of the current directory and
place the files there), and issue the command:
cvs -d :pserver:[EMAIL PROTECTED]:/cvsroot-freemware checkout freemware
After the command has finished, you can change to the 'freemware' directory
and configure and build FreeMWare as usual (consult the README file).
Whenever the CVS repository has changed and you want to update your copy
to the current version, simply go to the 'freemware' directory and type:
cvs update -APd
[ If this looks strange, here's the explanation: The '-A' switch asks CVS to
forget all sticky tags, dates, or -k options you might have set on your tree.
(That is, if you have deliberately checked out an old, named, version
instead of the current version, you'll need to give the '-A' flag to
reset the tree to track the current version again.) The '-Pd' flags
ask CVS to track directory changes as well, i.e. create directories that
have been added to the repositiory in your copy as well, and remove now
unused directories in your copy. ]
Note that 'cvs update' only downloads *changes* over the wire, so it should
be fast (comparable to downloading and applying a patch). To make it even
faster, you can ask the CVS server to compress everything sent over the line:
cvs -z3 update -APd
(The -z option can be given with every cvs command ...)
CVS makes a host of other commands available, mostly having to do with
version tracking and the like. For more information about this, please
consult the CVS documentation ...
CVS ACCESS ON THE WEB:
There's a copy of the 'cvsweb' CGI package installed on the FreeMWare
home page that allows to track the complete version history on the Web.
This is available at the URL:
http://www.freemware.org/cgi-bin/cvsweb.cgi
[ This appears to be broken currently; I hope we can fix this soon ... ]
CVS SNAPSHOTS:
From time to time (maybe every two weeks, or else after major changes),
I'll export a snapshot of the current CVS tree in the form of an .tar.gz
tarball, which can be downloaded via FTP from the FreeMWare web site.
This is to allow users without CVS access to stay up-to-date with the
development of FreeMWare.
Until we have a first stable release, those snapshots will be marked
'for developers only' and will carry just the current date as version
number. As soon as we have something stable that is actually useful
for users, we might switch to a regular versioning scheme.
CVS ACCESS POLICY FOR DEVELOPERS:
If you want to contribute to FreeMWare, there are two ways to do so:
The simplest way is to create a patch containing the modifications
you want to make, and send this patch in to the freemware mailing list.
(It's probably best to choose a subject starting with PATCH: or so ...)
The patch will be taken from the list by myself or one of the other
developers with CVS write access, and if everything is OK, be applied to
the current FreeMWare version and committed to the CVS tree.
If you are a regular contributor, you can also get an account allowing
you to commit your changes to CVS directly. I haven't set up any definite
policy for this; if you are interested, just drop me a note.
The rest of this text describes the practical details of how to make
changes, either by sending a patch, or by direct CVS access.
CREATING PATCHES AGAINST THE CVS TREE:
If you want to contribute to FreeMWare, but do not have write access to
the CVS tree (see below), you should send your modifications in the form
of patches against the current CVS version to the freemware mailing list.
There's basically two ways to do so:
- Use 'cvs diff'.
This means that you perform your modifications directly in the copy
of the repository created by 'cvs checkout' and kept up-to-date via
'cvs update'. Once you are satisfied with your changes, type
cvs diff -u
in the main 'freemware' directory, and send the output of that
command as patch to the list.
- Use *two* copies of the repository.
That way, you can keep the checked-out copy always identical to
the CVS tree, and perform your development on a *second* copy
(just copy the first one with 'cp -r' ...).
When you want to create a patch, make sure that the first copy
is up-to-date using 'cvs update', and the *second* copy is in
a clean state ('make dist-clean') and type:
diff -urN <path-to-first> <path-to-second>
There's advantages and disadvantages to both methods; just use the way
you prefer. You are free to do it completely differently, of course,
the patches you send in should preferably conform to these conventions,
however:
- unified context diffs (resulting from 'diff -u')
- apply cleanly against the current CVS version
Please rememeber to send in a short description of what the patch is
supposed to do, and add a 'change log' message that should be used
when the patch is applied to CVS (see below).
CVS WRITE ACCESS:
If you have write access to the CVS repository, you can commit changes
directly to the CVS tree. To do so, you'll need to check out the current
tree under your user account (instead of anonymously) by issuing a
cvs -d :pserver:<username>@lightning.fastxs.net:/cvsroot-freemware login
command, where <username> is your user name instead of 'cvs'. You'll have
to enter your password as well, of course. Then, check out as usual (still
with the CVS root containing your user name).
After you've perform your changes, you can then issue a
cvs commit
command. This will ask for a log entry (which should concisely describe
the purpose of the committed change), and then integrate the changes
into the CVS tree, creating new versions of all modified files.
Note that this works only if all you've been doing was to modify existing
source files. If you want to add a new file, or remove an old file that
has become obsolete, you'll have to issue a
cvs add <filename>
or
cvs remove <filename>
*before* the 'cvs commit'. In the case of new directories, you'll have
to first 'cvs add' the directory, and then add all the new files inside
the directory; similarly for removing directories.
Note that there is no simple way to *rename* files or directories;
you'll have to first remove the file under the old name, and then
add the file under the name. This has the effect that the new file
starts with a new version history; the change log of the old file is
still available (under 'Attic/'), but you'll have to access it under
the old name ...
Especially for directories this is ugly (as it affects the version
histories of *all* files under that directory), so renaming directories
should be avoided if at all possible. This means think twice about
the directory structure / names before adding a new directory!
VERSION HISTORY AND CHANGE LOGS:
cvs maintains a change log automatically for each single file:
Every time the 'cvs commit' command is issued, it asks for a change log
message describing the current modifications. This message will be
added to the change log of each affected file.
NOTE: To have meaningful change log messages, you should *not* commit
a lot of different changes in a single bunch; instead try to issue
a separate 'cvs commit' command for every group of changes that
form a logical entity (one new feature added / one particular bug
fixed ...).
Similarly, if you send in patches, try to make *several* patch files
if you implement different, independent changes instead of bunching
it all together into a single patch file. This will simplify adding
the changes to CVS with the correct change log messages ...
In addition, we have the main 'ChangeLog' file. As far as CVS is concerned,
this is just a normal source file like all the others. So, if you want to
add an entry to this file, just send in a patch or commit a change as usual.
(Note that it might be preferable to have the ChangeLog file contain the
same info as the CVS change logs; this could be automatically generated ...
What do you think?)
--
Ulrich Weigand,
IMMD 1, Universitaet Erlangen-Nuernberg,
Martensstr. 3, D-91058 Erlangen, Phone: +49 9131 85-7688
