Using CVS to keep in synch and contribute to Open Source Projects

By: Leonel Togniolli

Abstract: This article explains how to keep up-to-date with and how to become an active contributor to Open Source projects using CVS. By Leonel Togniolli

Using CVS to keep in synch and contribute to Open Source Projects - By Leonel Togniolli

With the recent release of TurboPower's component as Open Source, a lot of people became interested on knowing how Open Source projects work. CVS plays a great role on these projects, and I'll explain how to keep up-to-date with the files, and how to become an active contributor.

Even though I'll give focus to Open Source projects, TortoiseCVS and SourceForge, the concepts apply to other projects and diferent CVS clients and servers.

CVS is short for Concurrent Versions System. It allows multiple developers to work together in one project, handling merging of fixes and making sure everyone is working in the most recent version of the source code. It is also useful for the users that like be in the "bleeding edge", having the latest fixes, enhancements, and changes. Keep in mind you might be getting the lastest bugs included in these changes, and CVS code is often considered unstable. If you can't take the risk, hold on to regular stable releases.

I use TortoiseCVS to access CVS on the Windows plataform. It is meant to be very user friendly, and integrates with windows shell. The latest stable version, at the time of this writing, is 1.2.2. Download it and install. You might need to reboot.

If you are feeling adventurous, you can get the unstable build, download the latest code from CVS and build it with Borland C++ Builder, as a way to apply the concepts I'll explain next. :)

When the setup is done, right click on a folder to see the new context menu. It should look like this:

Make New Module is used to create a project in a CVS Repository you have write-access on. You can find SourceForge specific instructions on setting up a project on SourceForge Setup for Win32 Project and SourceForge HowTo. Thanks for Michael Silver for the links. You have also two quick-get items, where you can get the sources to TortoiseCVS and wxWindows, and the Preferences dialog, where you can tweak it some of its behavior. But I'm sure you want to download some fresh code. Click in the CVS Checkout menu item and the following window should appear:

We are going to checkout JVCL. From their SourceForge CVS page, their cvsroot is :pserver:anonymous@cvs.sourceforge.net:/cvsroot/jvcl. Paste that string on the cvsroot edit box, or, alternatively, fill up individual boxes. If the server supports module listing, you can click Fetch List to get a module listing. Otherwise, you must get the modules names somewhere else. If you follow the Browse CVS link in the right side of the page where we got the JVCL's cvsroot, you will get to the CVS Browser Listing. There you can see the available modules. We are going to get the module called jvcl. Type that (it's case sensitive) in the module edit box and press OK. This will start the checkout of the library:

JVCL is a faily big library, and it might take a while do be fully downloaded. You can continue to explore CVS features while it works, so enter the folder created by the checkout process and right-click on it. There's a new context menu:

CVS Update will check the freshness of all files, and download newer files. If you have changed a file in your local copy, and someone have commited a change to the same file to the repository, the changes will be merged to your local copy. If you have changed the same portion of the code, a conflict will occur. You can use a conflict resolver to solve it, fix it manually or delete it and download it again (or easier, getting a "clean copy", more on this later). CVS Commit will try to upload files you changed to the server. You can't do it right now, since you made an anonymous check out. We will do it when we set up developers access with SSH. CVS Add Contents will show a list of file that are present in your local copy, but not on the CVS Server, and will give you the ability to add the files to the repository. You will need write-access to do this. On the submenu, you have a shortcut to the Web Log of the module, where you can get diverse info about its files history and do diffs between different revisions of the files. If it can't find automaticly SourceForge Web Log, you will need to inform its prefix. It's http://cvs.sourceforge.net/cgi-bin/viewcvs.cgi. You can also use Make Patch to save a file containing your changes, which can be submitted to the project mantainers. In the Update Special item (also acessible through ctrl-clicking in the Update item), you can retrieve a specific version of the module, or change to a branch. Also, this is where you can get a clean copy of a file. Here's the Update Special screen:

Below Update Special, you can create a Tag (used to mark a release, for example, so you can later retrieve the files they way they were in that particular version), create a Branch (so development can be done without affecting the main branch - a unstable branch, for example), or Merge the changes from a revision/tag/branch in your local copy. After creating a Tag or a Branch, you should use the Update Special feature to change to the new Branch or Tag.

TortoiseCVS features icons overlays to help you see the status of the files. Here you can see unchanged files (green), files with local changes (red), files with a conflict (purple) and files not in the repository (question mark), in the default icon overlay set:

If you right click a file, the context menu is very similar to the one shown in a folder, but its actions will only apply to one file. Here's how it looks, on a changed file.:

You can see that is has some new actions: You can request a CVS Diff, from the file in the repository. If you don't have a diff application, try TextDiff, form Angus Johnson. You can use History to see the log of all changes of a file, and request a diff from a particular revision. Revision Graph is where you can graphically see the branches, tags and revisions of a file.

But I want to contribute!

In a regular CVS server, you can have write access to repository with this setup, only using a username/password instead of checking out anonymously, but SourceForge requires SSH authentication, for better security. It's a bit more complex to setup, but it's not hard. You will need Putty. Download it and unzip it to a folder. Run PuttyGen and click the Generate button to generate a public/private pair of keys, and save them somewhere safe.

You should now go to SourceForge, log in, and go the "Account Properties". If you are listed as a developer in any project, you should be able to upload your public key. When you have uploaded your key sucessfully, you can checkout files using your SourceForge username: you will not be anonymous anymore. But you will need your private key loaded for authentication, and Pageant is the tool that will do it. I have created a shortcut to run it with the following command line: "D:Puttypageant.exe .ssh/burnin.key", and I run it whenever I need SSH access to SourceForge, but you can put it on your Start Up folder, or even run it and manually load your key file. It will ask for your passphrase, if you specified one when you created the key, and stay in the system tray.

The process of checking out files now is the same. You just have to put in your username on the CheckOut dialog, and if Pageant is running, it won't even prompt you for a password. Now you we can check out the last dialog, CVS Commit:

Here you should write what you changed in the file. Double clicking in one of the files will launch the Diff Viewer so you can remember what was changed.

And it's done. Don't forget that you can setup your own private CVS server, or use different clients, that the basics will be the same. Now, have fun, and don't forget to contribute to at least one of the many Delphi Open Source Projects.


Server Response from: ETNASC03