Feingold08 > RussForge

Getting Started

Getting Started

Ready to get started? This page will walk you through the steps.

Get A SourceForge Account

The first step is to get a SourceForge account. It's free and easy, and takes about two minutes. You can get an account by clicking here.

Let a RussForge Administrator Know You Have Your Account

It's a good idea to start this step early, because it will take a while for us to get your e-mail and add you to the RussForge project. The e-mail can be as simple as "Please add me to the RussForge project, my username is Xydlfrak," or, if you want, you can tell us a little about yourself and your interests. Either way, shoot off an e-mail to tj_willis (at) sourceforge (dot) net.

Note that in some cases, you could be added to the project before your sourceforge e-mail address is active.

Get A CVS Client

A CVS Client allows you to interact with the repository. If you use UNIX, chances are it's already installed on your system. If you use a Macintosh, MacCVS is available here. If you use Microsoft Windows, I recommend TortoiseCVS, which is available here.

If you install TortoiseCVS, it will want you to reboot the computer afterwards. You might want to bookmark this page before you start the installation.

Set Up Your Client

Now that you have your CVS client, you need to tell it where the repository is. This is done by setting a variable called CVSROOT. Regardless of what kind of computer you use, you want your CVSROOT to looks something like this: :ext:YourName@cvs.sourceforge.net:/cvsroot/feingold08, where YourName is replaced by your SourceForge username.

Setting up on a Windows system using TortoiseCVS is particularly easy. Go down to the Windows "Start" menu and open up "My Computer." Then find a convenient folder like "My Documents." If you go to the "File Menu" there should be a menu item called "CVS Checkout." A program should pop up with some boxes to fill in. We have to fill in 5 of them, like this:

Protocol: Secure shell (:ext:)
Server: cvs.sourceforge.net
Repository folder: /cvsroot/feingold08
Username: TheSourceForgeUserNameYouMadeInStep1
Module: russforge

Setup Screen Capture

Now, up towards the top, there's a box labeled CVSROOT. It should be all filled out and read something like this :ext:YourName@cvs.sourceforge.net:/cvsroot/feingold08.

Check Out the Repository

In order to get the files onto your computer (to "check out the repository" in CVS parlance), you have to be a member of the project. You can check here to see if you've been added.

Assuming you're a project member and you have your CVS client all set up, the next step is to check out the repository. If you're following along with the TortoiseCVS setup, all you have to do is click the "OK" button from the previous step. You'll be prompted for your SourceForge password one or two times, and it will download the files into the directory you've selected.

Tortoise will tell you when all the files are downloaded. Click "OK" and take a minute to look around the files in the repository.

Modify A File

OK, so you've got a copy of the repository on your computer. Let's play with CVS for a couple of minutes to get used to how it works.

In the russforge directory, there should be a file called README.txt. Let's vandalize it!

Notice that the file has a green icon with a checkmark on it. That shows you that you haven't modified it. Open the file up in your favorite text editor and type something in. It doesn't matter what it is: something like "Hello world" will work fine.

Now save the file (as plain text), and take another look at the folder. The green logo with a checkmark should be replaced by an orange icon with an arrow. This indicates that you've modified the file. Now it's time to share your work with the world.

A Modified File

If you right-click on the icon, a menu with a bunch of different options should show up. Look for one that says "CVS Commit" and click it. CVS Commit Dialog. A dialog should pop up asking you for a cooment. This is an opportunity for you to describe the changes you made. When you're satisfied, click "OK." Tortoise will upload the file to the repository, and probably ask you for your password. When everything is done, README.txt will have a green checkmark icon again.

Adding a New File

There should be a directory named "misc" in your russforge directory. Let's go there and add a new file. It can be any kind of file. You can copy one in from some other directory on your computer or save a new file from your text editor there. Notice that its icon has a blue question mark, indicating that it hasn't been added to the repository yet.

A File That Isn't In The Repository

Now, right-click on the file just like you did before, and there should be an option called "CVS Add." Choose that and click "OK." You'll get a notice that you need to do a "CVS Commit" to add the file permanently. Also, notice that there's an orange plus-sign icon on the file. This means that it's been added, but not committed.

A File That Is Added But Not Committed

So, let's commit the file. Right-click on it and click "CVS Commit." Just like your commit in the previous section, you'll be asked to make a comment about what you're doing and asked for your password. The file will be uploaded to the repository, and when everything is done, the file will have the familiar green checkmark icon.

Deleting A File

You can use the "CVS Delete" menu item to delete a file. Notice that, as when adding a file, you have to do a commit to make the delete permanent.

Updating Your Local Repository

What happens when someone else updates a file? Do you automatically get their updates? The answer is yes and no.

To get an update, you have to tell CVS you want one. Go up to the russforge directory and right-click (not on a file this time). If this doesn't make any sense, just go up to the "File" menu. You should see an option called "CVS Update." When you click that, you'll be asked for your password, and any new files will be patched into your local copy of the repository.

Advanced Topics

It's a good idea to do commits and updates regularly. This minimizes the chances of a "collision" where two users make conflicting changes to the same part of a file. With frequent commits and updates, this almost never happens.

If you get tired of typing in your password all the time, you can create a digital signature key for your computer. Information on how to do that is available here.

Everything you ever wanted to know about CVS is available at Sourceforge and here.