CVS access parameters

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 plex86 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 plex86 CVS repository for the first time, you need to log in to the CVS server:

    cvs -d :pserver:cvs@lightning.fastxs.net:/cvsroot-plex86 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 'plex86' of the current directory and place the files there), and issue the command:

    cvs -d :pserver:cvs@lightning.fastxs.net:/cvsroot-plex86 checkout plex86

After the command has finished, you can change to the 'plex86' directory and configure and build plex86 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 'plex86' 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 plex86 home page that allows to track the complete version history on the Web. This is available at the URL http://www.plex86.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 plex86 web site. This is to allow users without CVS access to stay up-to-date with the development of plex86.

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 plex86, 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 plex86 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 plex86 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

• 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 'plex86' 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  
  

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:@lightning.fastxs.net:/cvsroot-plex86 login

command, where 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 

    cvs remove 

*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.

Written by Ulrich Weigand <weigand@informatik.uni-erlangen.de>