GettingStartedWithSourceForge

Here's a long list of stuff required to get set up with SourceForge?, Putty, and WinCvs?. It is not in perfect order, but it should cover everything:

NOTE: in order to do any of this on the AutoRealm? CVS repository, you have to added as a developer. If you want ti be added as a developer, send a request to the AutoRealm? Yahoo Group and explain in just a few words why you want to be an AutoRealm? developer. One of the things that you should mention is how familiar you are with Delphi.

BEFORE YOU BEGIN

1. Install Putty, and put it's directory in your PATH.

2. Install WinCvs?, and put its directory in your PATH.

3. Add the environment variable CVS_RSH=C:\path\to\plink.exe to your environment variables (under Control Panel >> System in Windows XP).

4. Create a public/private key pair in puttygen (included with Putty).

5. Copy the public part of your key from the puttygen screen and pasted it into your key area on SourceForge?.

6. Place both of those keys in the /Putty/keys directory.

7. Start pageant.exe (found in the Putty directory), and add your private key to it (you have to do this every time you start it -- annoying, but it's a security measure).

INITIALIZING YOUR ACCOUNT

After you have uploaded the public part of that key to SourceForge? (and waited six hours for it to be active), you have to connect to cvs.sourceforge.net with Putty to download the server's fingerprint to your own machine before you can connect with WinCvs?.

1. Run Putty.

2. 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".

3. 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. Type "Y". (If we were doing something commercial or secret, I'd put more here about verifying the fingerprint, but for AutoRealm? just go ahead

4. PuTTY? will prompt you to enter your SourceForge?.net user account username and password.

5. Upon successful authentication, cvs.sourceforge.net will create your home directory, 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.

6. You have successfully installed and tested PuTTY?; if it didn't go as smoothly as I'm making it sound, ask for help. :)

The next step is to set up Pageant and WinCvs?.

GETTING A MODULE FROM CVS

Obtaining a module from the CVS server for the first time is known as a "checkout". Checking a module out from the repository gives you a local copy of the directory hierarchy that makes up the module. To perform a checkout, do the following:

1. Have Pageant running with your private keys in it.

2. Choose the Cvs Create -> Checkout module menu.

3. In the file dialog that pops up, enter these values (without the quotation marks, of course):

4. Checkout Settings: Module name and path is "autorealm". Local Folder to checkout to is up to you. Mine is "C:\Documents\CVSData?\cvs.sourceforge.net\cvsroot" A directory named after the module will be created in the directory you supply, so you will normally want to provide the directory in which you keep all of your SourceForge? projects. Leave the other fields blank.

5. Checkout Option: leave these blank.

6. Merge Options: None.

7. General: Authentication is "ssh". Click Settings, and check "If ssh is not in Path". In the text box underneath that, put the path to plink. Mine says: "C:\Program Files\Putty\plink.exe". Check "Additional ssh options". In the text box underneath that, put "-ssh". Click OK to go back to the General tab.

8. In the CVSROOT text box, type this, replacing "username" with your SourceForge? user name: ":ext:username@c...:/cvsroot/autorealm"

9. On the Globals tab, these are optional, but this is what I check: "supply controls when adding files" "dirty files support" "prune empty directories" "checkout text with unix LF" Only do this last one if you have a good text editor that knows how to handle Unix-style linefeeds. If you don't know what this means, then don't check this box.

10. Press the OK button.

If everything goes as planned, WinCvs? will start downloading the files. When it's done, there will be a message in the bottom window that says something like "CVS returned Code 0". WinCvs? may also leave a DOS-style command window open after CVS is done. When you see the "CVS Returned Code 0" (or Code 1) message, it's OK to close this DOS-window.

UPDATING YOUR LOCAL CODE, THEN UPDATING THE REPOSITORY

When you are happy with your local code (it compiles and works), you first update your code to bring it into line with the main repository. Then you send your local changes to the repository to be included there.

GETTING OTHER PEOPLE'S CHANGES FROM CVS

The process of getting changes from the server to your local copy is known as "updating". Updating may be done on single files, a set of selected files, or recursively on entire directory hierarchies. To update, do the following:

1. Select the directory, file or files that you want to update.

2. Click the right mouse button on the selction, and choose the Update selection menu item.

3. Make sure Create missing directories that exist in the repository is checked.

4. Press the OK button.

Changes done by others will be merged into your files, keeping any changes you may have done to the same files. The repository is not affected by an updating.

If you receive reports of conflicts during the update...

RESOLVING CONFLICTS

Once in a while, the CVS server will report a conflict when you update your files from the repository. A conflict occurs when two or more developers have changed the same few lines of a file. As CVS knows nothing of your project, it leaves resolving the conflicts to the developers. Whenever a conflict is reported, you should open the file in question, and search for lines starting with the string <<<<<<<. The conflicting area is marked like this:

<<<<<<< filename
your changes
=======
code merged from repository
>>>>>>> revision

You should decide what the code should look like, do the necessary changes, remove the CVS markup, and commit your modifications to the repository.

SENDING YOUR CHANGES TO CVS

Making local modifications available in the repository is known as "committing" the changes.

1. Before committing, you should do an update to make sure there are no conflicts. See Getting Other People's Changes from CVS, up there ^.

2. Select the directory, file or files that you want to commit.

3. Click the right mouse button on the selction, and choose the Commit selection menu item.

4. In the Commit settings dialog, enter a log message. This step is optional, but it is highly recommended that you take some time to shortly describe what was changed. This is really important in case what you do breaks something, and the team is trying to find out what happened.

5. Press the OK button.

Please note that committing changes will not automatically add new files that you have created to the repository. You have to add them yourself, like yesterday when John had to add the older files that Andy wrote.

Good luck!

bblackmoor@blackgate.net 2002-08-18