CVS Co-operative Mode

With the co-operative method of working, the files on your machine are read-only and you will not be able to change them until you have used the cvs edit command as described below.

Using DOS Commands

The file system on any disk begins with the root (top-level) directory, represented as a backslash. Thus C:\ represents the root directory on the C: drive. Each additional nested directory can be represented as another element in the path, with a backslash used to separate each one. C:\Windows\System\Colour, means that the Colour folder is in the System folder in the Windows folder on the C: drive.

When you open a DOS window you should see a command prompt such as C:\>. The first letter indicates which drive is currently in use - the 'active' drive.

If you want to change to a different directory, say to the colour directory, you would type cd c:\system\colour and press 'Enter'. The command prompt will then change to C:\system\colour>, showing that you are now in the colour directory.

Note: File names for the CVS repository, on UNIX, are case sensitive. Therefore, to make things simple for yourself always treat the file names in CVS as case sensitive.

Environment Variables

• Set home=c:/freebmd (this lets CVS know that freebmd is the 'home' directory in which the files are to be stored). Note: The forward slashes are intentional.
• Set cvs_rsh=c:\program files\cvs\ssh (this lets CVS know where the secure shell files are).
• Path=%path%;c:\program files\cvs (the path is searched for executable files) Note: the percentage signs ensure that the 'Path' is added to any existing path command, and does not replace it.

Note: The environment variables above assume that you will name the folders as in the 'Sample session' section below. If you name the folders differently, then you need to change freebmd and cvs in the environment variables accordingly.

Presetting environment variables

• Right click on My Computer - Properties - Advanced - Environment variables - New.
• Enter the variables in the top pane thus: HOME, CVS_RSH and PATH.
• In the bottom pane add the rest of the variable, for example: c:\program files\cvs

Click on the Autoexec.bat tab and look for a 'PATH' command. If there is one, click on edit and add your PATH command to the end of the existing one. If you don't see a PATH command, click on new and add the command. Add the HOME and CVS_RSH variables here as well.

A Sample Session

1. The first thing you need to do is create a new folder on your hard drive. The naming of this folder is arbitrary, but for this example we will call it 'freebmd'. The folder will contain the FreeBMD files that you will download from the repository. The path to this folder will be C:\freebmd
2. Next, create a folder in the Program Files folder on your hard drive and name it 'cvs', so the path to this folder will be C:\Program Files\cvs.
3. Now you are ready to download the cvs_ssh.zip file containing the CVS software and associated routines including SSh (secure shell).
4. When you have downloaded cvs_ssh.zip, extract the files to the cvs folder you created in step 2.

Creating Keys

1. Connect to the internet in your usual way.
2. Open a DOS window and navigate to the 'Home' directory, c:\freebmd (if freebmd is the name you are using). You always have to be in the home directory before downloading project files.
3. If you haven't preset the environmental variables as described above, you will have to type them in now, exactly as shown under Environment Variables, but substituting the folder names for the ones you have chosen.
4. At the command prompt, type ssh-keygen. The key generation program will now be executed. When prompted for the file in which to save the key accept the default offered and press enter. It is most important that the file is literally called Identity.pub and is in c:\freebmd\.ssh (if freebmd is the name of your home directory).
5. You will be asked to supply a passphrase (password) that you will need to authenticate your use of SSh. Choose an obscure password that only you will know, and write it down, as you will need it again.

Note: If you haven't entered a password in a DOS window before, it can seem a bit strange. As you type, the cursor doesn't move, giving the impression that nothing has been entered. You will be requested to enter the password twice.

If all has gone well, the file Identity.pub will have been placed in c:\freebmd\.ssh.

6. Send the file called Identity.pub to Dave Mayall. This file contains your public key.

Note: In the same location as identity.pub, ssh-keygen will have stored another file called Identity. This is your private key which enables you, and only you, to authenticate messages signed with your public key.

Once you have run ssh-keygen and have sent identity.pub to Dave, do not run it again, as your key will be overwritten, and you will have to re-send the file to Dave.

7. Dave will set up a login (referred to as yourname below) for you on the FreeBMD development machine. You will receive an e-mail message from Dave notifying you of your login name, and password for PTS.
8. It would be wise to ask Dave to set you up to be mailed with all CVS commits

Getting the Project Files from the Repository.

1. Make sure the environment variables are set.
2. Make sure you're in the home directory by typing at the command prompt:
   cd c:\freebmd
3. Download the source from the repository by typing the command:
   cvs -d yourname@test.freebmd.org.uk:/home/cvs checkout UKGEN-FreeBMD

Note: Remember case sensitivity. Make sure you type UKGEN-FreeBMD exactly as shown. You will be prompted for the passphrase you created earlier with ssh-keygen.

4. Enter your passphrase. The next stage takes some time, and you may think nothing is happening. Be patient! There are a lot of files to download. Eventually the files in the repository will start to download into your home directory. The download will be complete when you are returned to the DOS command prompt.
5. During the download process a folder called UKGEN-FreeBMD will be created inside the home directory, and will hold all the downloaded project files and folders.

Making Changes [Developer]

Note: Before making any changes to a file, make sure you have allocated the task to yourself in PTS

1. Type cvs update
   to ensure that your local copy of the repository is up to date.
2. Type cvs editors filename
   to find out if someone else is editing a file. If so you will need to negotiate with them, or with whoever is co-ordinating the editing activity before proceeding.
3. Type cvs edit filename
   to indicate that you are going to edit a file. This makes the file read/write and informs other users that you are going to edit it. If someone else starts to edit the file (they shouldn't) you will be notified by email.
4. Look in the rootsweb-FreeBMD2 folder for the file you want to work on and make the necessary changes.

Note: Use a plain text editor for editing HTML files, as a WYSIWYG (What You See Is What You Get) editor can mess up the code. View HTML files in both Internet Explorer and Netscape Navigator if possible before upload.

5. Type cvs update filename in case the file has been changed in the meantime.


6. If you decide to abandon the changes you have made, and revert to the orignal version, type cvs unedit filename
   You will not be able to edit the file again until you have done a cvs edit file

Committing the Changes

1. Type cvs commit filename to make your changes into the repository. CVS creates the next revision number of the file. You will not be able to edit the file again until you have done a cvs edit filename
2. CVS goes quiet for a moment while it compares the list of files on your computer with those on the server, and then it automatically opens up Notepad showing a list of changed files.
3. At the top of Notepad you will see the cursor. Type in a short comment here to describe the changes to the file(s). Click on File - Save and close Notepad
4. When Notepad closes, CVS automatically sends your edited files to the server. At the same time, an e-mail is generated and sent to everyone on the mailing list telling them what has been changed.

Note: There is an alternative to using Notepad when committing in step one. Replace the command shown with cvs commit -m "message" filename where message is the description you would have typed into Notepad.

Testing the Changes

1. Log on to the Development server . You will see a list of files, including the file you have changed, preceded by a letter 'u' to indicate the file has been uploaded.
2. Test HTML and CGI changes on the Test site. The test site looks and acts like the FreeBMD site. You can navigate through the site and test how your changes look and behave.
3. Once you are happy with your testing, go to PTS and change the task status in PTS to "Ready for Test" and assign it to the person who originally requested it.

Tip Put the development server, the test site and PTS login into your 'Favourites' folder. You can then move easily from one to the other .

Requesting Transfer to Production [Developer]

1. When the requester is satisfied with the changes, you will receive an e-mail notification that the task has been assigned back to you as "Tested OK"
2. You now have to 'tag' the changed file. Make sure you're in the folder/directory which holds the file. Tag each changed file by typing cvs tag T1234 filename
• Replace T1234 with the TID from PTS preceded by T 
• Replace filename with the name of the file. 
3. Add a followup to the task in PTS, listing which modules have been changed, list any restrictions about when the module must go live (e.g. "To go live after next DB update") and assign it to Dave Mayall in status "Ready to Deploy".
4. The process is complete when Dave puts the changes live.

Additional Information

The most common commands

• cvs commit - commit your changes into the repository. 
• cvs update - get the latest version of a file from the repository. Your modifications to a file are never lost when you use update. If no newer revision exists, running update has no effect. If you have edited the file, and a newer revision is available, CVS will merge all changes into your working copy. 
• cvs status - find the latest revision in the repository and compare it with yours. When you use status, one of a number of messages will be output. The following are the ones you are most likely to see: 
• Up-to-date: The file is identical with the latest revision in the repository.
• Locally Modified: You have edited the file, and not yet committed your changes.
• Unknown: CVS doesn't know anything about this file. For example, you have created a new file and have not run add.
• cvs diff - find out how your version of a file differs from what is in the repository. This is useful to see what changes you have made. 
• cvs log - find out what happened to a file. 
• cvs add - create a new file 

Note: Using the above commands without stipulating a filename will act on all files. If you want to commit or compare one file, give the filename thus: cvs update filenane You will be prompted for your passphrase (as defined in ssh-keygen) when you execute each command.

General update

Creating a new executable file

Whatever the Windows permissions are on the file that is created (using cvs add ...), it will not have the executable bit set on the server. If you have access to the development machine you can go into source and add the execute permission manually ... or get Ben, or Dave, or Graham to do it for you!

Binary files

If you create a binary file, use the -kb option on the add command, thus

However, there is a problem! When you do the first commit on the file CVS puts the whole of the binary in the commit mail message. Therefore, the socially responsible thing to do is to make the first commit a dummy file and then commit the real file as a second commit.

Creating a new directory

Getting a previous revision

Documentation

Abbreviations

Using plink

Create a PuTTY saved session

CliCK on the + next to Connection and then click on SSh

Click on Session and type a name (e.g. cvs) in the Saved Sessions box and click on Save. We will refer to this name as cvs-session below.

Note for Windows XP users: The first time you use PuTTY you should change the default encryption cipher selection policy to 3DES.

Create a session

Note that the security of FreeBMD is now dependent on the security of your machine. Ensure you have a secure logon and timeout. Close your machine when not using it.

Change cvs protocol

Change cvs directory

In order to run any of the cvs commands using plink instead of ssh include -d cvs-session:/home/cvs where cvs-session is the name you saved your PuTTY session under.

FreeBMD Main Page