CVS access for developers

To gain write access to the ELML CVS respository you must be an authorized developer. Before reading this manual, please be sure that you have a valid Sourceforge Account. Also be sure to that you have read the last page about downloading ELML and that you understand the concept of CVS and how it works. If these requirements are fulfilled, then continue with the following manual.

Gaining access to the ELML CVS repository on Sourceforge requires two steps:

1. Generating and importing an SSH key
2. Configuring your CVS client

This manual is written for Windows not because I specially like Windows but because most of our developers use XMLSpy as their XML Editor and this software is only available on Windows.

Generating and importing an SSH key

1. Download and install the binary version of PuTTY containing all the tools. At least install PuTTY (the SSH client) and PuTTYgen (the key generator), if you want to be minimalistic :-)
2. Open PUTTYGEN.EXE and select the desired key type ("SSH2 DSA", within the "Parameters" section). Sourceforge uses SSH2 DSA!
   
3. Now click on the "Generate" button and follow the on-screen instructions ("Please generate some randomness by moving the mouse over the blank area"). Key generation will be performed immediately afterward.
4. Enter username@shell.sf.net in the "Key comment" field, replacing 'username' with your SourceForge.net user name (eg. JoelFisler). This comment will help you to identify the purpose of this key.
5. Enter the desired passphrase in the "Key passphrase" and "Confirm passphrase" fields. Be sure to know your password, there is no way to retrieve it if you loose it!
   
6. Click on the "Save private key" button; use the resulting dialog to save your private key data for future use. Use a filename such as "SourceForge.ppk". The .ppk extension is used for PuTTY Private Key files.
   
7. Go to the SSH key posting page on the SourceForge.net site. Copy your public key data from the "Public key for pasting into OpenSSH authorized_keys2 file" section of the PuTTY Key Generator and paste in to the provided form on the SourceForge.net site.
   
8. Exit the PuTTY Key Generator and wait about 15 minutes until your key on Sourceforge becomes active (time for a coffee break :-)

Meanwhile you can create your home directory on the Sourceforge server. This is done automatically when you access Sourceforge via SSH the first time. You only have to do this once. Here is how it works:

1. Open the PuTTY SSH client. Enter 'cvs.sourceforge.net' as the host name you wish to connect to, and select 'SSH' as the desired Protocol. For clarity, select the 'Never' radio button within the 'Close window on exit' option, then click 'Ok'.
   
   
2. Select the Connection -> SSH category of the configuration frame on the left. Ensure the Preferred SSH option has the '2' radio button selected.
3. Select the Session category of the configuration frame on the left. Type a name in to the 'Saved Sessions' box, such as 'cvs.sourceforge.net'. Click the save button. Next, click the 'Open' button. The connection to cvs.sourceforge.net will be initiated and you will be prompted to verify the host fingerprint for the cvs.sourceforge.net host.
4. PuTTY will prompt you to enter your SourceForge.net user account username and password. Enter the same password and user login that you use to login on the SourceForge.net web site. Upon successful authentication, cvs.sourceforge.net will create your home directory, and then log you out automatically. This is normal; there is no other reason to interactively sign-in to cvs.sourceforge.net than to have your home directory created.

Now we are finished with all the SSH/key-stuff, things that you only do once and then forget about it. Let's continue with configuring the CVS client.

Installing and configuring TortoiseCVS client on Windows

There are many Windows, MacOS, Unix CVS clients, both with a GUI or command line. I have chosen TortoiseCVS because it is a free OpenSource client and because it works via a context menu which makes it easier to update and commit files. If you like WinCVS better, check this guide. Here is what TortoiseCVS looks like:

How to install TortoiseCVS on your Windows host:

1. Download and install the latest TortoiseCVS binaries. Check that after installation the three CVS context menus (as in the screenshot above) appear.
2. Now configure and check the working of tortoiseCVS:
   • Create some temporary directory, open it in the explorer and do a right mouse click in the empty directory. From the context menu select CVS->Preferences: Here are some settings for the different Tabs:
   • Main: Under "Progress dialog" you can define if you would leave the console windows open or not after some operations. We recommend to put "Close manually". The "Progress messages" should be put on "Loud" to have a detailed console output. Use the Language of your choice, but our explenations refer always to the English version!!
   • Policy: Be sure to mark the first to Boxes "Empty folders" and Update creates missing folders". Else you will not get new folders and old emtpy folders will remain in your ELML_ROOT folder. The other boxes can all be disabled (refer to the manual for a detailed explenation).
   • Tools: We recommend that you install WinMerge for Diff and Merge operation. It is an OpenSource GUI tool that makes life easier :-) The installer will automatically put the right paths in the Tortoise Preferences. Check that the SSH application is TortoisePlink.exe (should be like this if you just made a default Tortoise installation).
   • For all other Tabs I either dont know what they mean or they are self explenatory. Please refer to the Tortoise manual/help for more information.
3. Now that Tortoise Preferences are setup corretly, you can checkout the ELML_ROOT module:
   • Open your temp directory in the explorer and from the context menu select "CVS checkout"
   • Under protocol use "Secure Shell (ext)".
   • Server is cvs.sourceforge.net (no port)
   • Repository folder is /cvsroot/elml
   • Username: Use your Sourceforge username here
   • Module: Click on "Fetch list" and choose the ELML_ROOT module (or enter it manually in the field). If you would like to participate as a ELML webmaster, you can also checkout the WEBSITE module and ask for write access.
   • This is what your cvsroot should look like after you did the above steps:
     :ext:<yourloginname>@cvs.sourceforge.net:/cvsroot/elml

For a detailed documentation about CVS on Sourceforge check the CVS introduction and the more detailed developers guide. General information about CVS can be found at the CVS website.

The last part is just to make your life easier.

Using Pageant for storing passwords

The PuTTY SSH client suite includes an application to help reduce the frequency that you need to enter your password. Upon starting your workstation, you may execute 'C:\PUTTY\PAGEANT.EXE' and configure it to have knowledge of your current SSH keys. By adding your key data to Pageant, you will need to enter your SSH key password only once, no matter how many SSH sessions you initiate while Pageant remains running. This step will need to be repeated each time you restart your workstation or Pageant.

1. Make use of Start->Run to execute 'C:\PUTTY\PAGEANT.EXE'
2. Double-click on the Pageant (computer with hat) icon in your system tray.
3. Click on the 'Add Key' button.
4. Select the key file we saved during the key generation process (C:\PUTTY\SOURCEFORGE.NET.PPK or something similar).
5. When prompted, enter the password you specified during the key generation process, then click 'Ok'.
6. The key in question will now appear within Pageant's active key list. While Pageant is running, Pageant will respond to any requests from other PuTTY applications (such as PuTTY.EXE and PLINK.EXE) that you enter your SSH key password.