How to become a developer of Jet3D

If You just have coded a nice extension object, fixed a bug or two and want to share your work with other developers, You need the developer's access to repository. There are some simple steps to follow:

Installation of the cvs-through-ssh package.

Get the binary distribution of the self-made toolkit I use to maintain this site. Unpack it into the root of any drive and read install.txt

Accessing the CVS repository

You do not need to login!

WinCVS Configuration - by Incarnadine


Some have had trouble getting WinCVS working with developer access, so I'm going to try to detail my config here.
First, make sure WinCVS is NOT loaded.

Next, make sure you have the ssh_cvs.zip file from the project web page at jetpp.sourceforge.net. Extract this file into a directory somewhere. For instance: C:\SSH

Set these environment variables in your autoexec.bat (or system settings under NT) Note, there was a typo in the install file:
SET CVS_RSH=c:\ssh\ssh.exe
SET HOME=c:\code
SET PATH=%PATH%;c:\ssh

C:\Code is just where I store all of my code files. That's where I grabbed the jet module to, so it's under c:\code\jet. You can make this HOME dir anywhere, but that's where it's going to create a .ssh dir. This .ssh dir will contain two files: known_hosts and random_seed. There's an optional step that I would recommend performing later where we'll copy two more files into this dir. At this point, you'll need to reboot so your paths get set (unless you're running NT).

After the reboot, now you can load WinCVS since the path settings are in effect. Go to the Admin/Preferences menu item. On the General tab, set the CVSROOT to:
yourdevname@cvs.jetpp.sourceforge.net:/cvsroot/jetpp

Set authentication to:
SSH Server

Use Version:
CVS 1.10

These are set under Globals:
Checkout read-only,
Use TCP/IP compression,
Dirty files support,
Prune,
Supply control when adding files.

This is important. Under Ports, the only thing checked is "Check for an alternate rsh name". Make sure you type "ssh" into the box if it's not already there.

Under the WinCVS tab, set your HOME folder to the same as you set up the environment variable. Click OK.

Now you're ready to retrieve the jet module. Some people may be able to skip this step if they've been using the command line CVS. Go to the Explore tab in the left pane. Select the directory you want to put the jet subdirectory (module) into. For me, this was c:\code. Now, go to Create/Check out module to selection. When the dialog comes up, you just type in "jet" for the module name and click OK.

You'll see WinCVS spawn a DOS window. If you go click on it, you'll see that it's completely blank. What's actually going on is SSH is waiting for you to type in your Sourceforge password. Type it into the window (you won't see anything) and then press Enter. After a few seconds, you'll see WinCVS performing the action you told it.

The jet module should now be stored wherever you specified. You can then go to View/Change browser location to set the dir that the modules tab looks at. I think it defaults to C:\. I changed mine to C:\Code at first, but since Jet is the only project I'm working on, it's now c:\code\jet.

You can perform any command following the same procedure. For instance, let's say you've got the module already and you want to make sure you've got the latest sources. Click the jet directory, then click the Update selected button or go to the menu Modify/Update selection. In the dialog that appears, I would recommend checking the box that says, "Create missing directories that exist in the repository," otherwise you may end up missing new files. Click OK.  When the SSH window comes up, type in the password and away it goes.

Ok, so typing in your password all the time gets old REAL quick. If you create a public key you don't have to do this. Your Sourceforge account gives you a UNIX shell account as well. I used KoalaTerm (an SSH1 telnet client) to telnet to shell1.sourceforge.net. Tell it to use SSH1 as the port and you'll type in your Username and Password. The Username is lowercase (remember UNIX is like that).

Once you're in, type "ssh-keygen". It'll ask you for a file name, just press enter, but note the location so you can go get it. It'll also ask you for a passphrase. Just leave this blank (press enter), otherwise you'll have to type the passphrase in instead of your password when SSH runs. You don't want that.

When it finishes, it'll create two files in the .ssh dir, one called "identity" and the other called "identity.pub". You need to download these files (maybe FTP them to another computer so you can get them). Place these 2 files in your HOME\.ssh dir on your local computer that was mentioned way above.
Then, go to www.sourceforge.net, log in via SSL, and go to "Account Maintenance". There's a place where you can edit your keys. Go there and copy/paste the contents of the file identity.pub into the text box. Submit it. In a few hours, the public key should go into effect and you will be able to access the CVS without having to type your password in.

Accessing a Branch - by Incarnadine

Branches are extremely useful.  They allow you to "fork" the code so that you can work on a separate code base from the main trunk.  This allows you to make whatever modifications you want, submit them back to the CVS server, etc. while leaving the main trunk in a stable state.  Other people can access the branch you're working on by simply requesting it using the procedure below.  Once your changes have been well tested, you can automatically merge your changes back into the main trunk.  Here's how to access an existing branch.

Whenever you tell WinCVS to "update" your files, you have to go to the Sticky options tab of the update dialog. Tell it to Retreive rev./tag/branch and type in the name of the branch you're interested in retrieving. Also, make sure the checkbox that reads, "If no matching revision is found, use the most recent one," is checked, otherwise files that don't exist in the branch will be removed from your local copy.  Click OK.

Once it retrieves your sources, then in the column on the right hand side that says "Tag", you'll see whatever branch your current working copy is using. Files have a blank tag indicate the main trunk.

For example, if you want to request the ActorCollision branch, just tell it to update the jet module, select ActorCollision in the sticky options, verify the checkbox, and then click OK. Then, if you go take a look at any of these files, you should see the ActorCollision tag next to the name:
ExtBox.h/c, Actor.h/c, jeWorld.h/c

How to Create a Branch - by Incarnadine


There are a couple ways to do it, particularly depending on the CVS client you're using. This is what I've been doing under WinCVS:

1. Select the file or directory you want to create the branch on.
2. Click the branch icon on the toolbar or go to the menu Modify/Create a Branch on selection.
3. A dialog will appear. Type in the branch tag name you want to create. If you selected a directory, select whether or not you want it to recurse into subdirs. Click OK. This will create the branch.
4. Now you need to request that branch become your working copy. Again, select the files/dirs you want. Then choose Modify/Update selection from the menu or toolbar. A dialog will come up. You need to go to the "sticky options" tab. Click the retrive tag/branch and select the branch you created from the drop-down list box. Click OK.
5. This will mean that you're now editing on that branch. You can then click Trace/Edit a selection on the menu or toolbar to edit the files. When you're done, you can commit the changes via the normal Modify/Commit selection option. It will update just the active branch you have checked out. WinCVS shows you which branch/tag name you're working on in one of the columns to the right of the files.

Branch Merge Procedure - by Incarnadine

Here's the procedure in WinCVS for doing a merge on a branch:

1. Update your project telling it to reset all sticky tags so that you're working on the main trunk again (not your branch).
2. Update your project again, this time going to the merge tab. Tell it to merge one branch and select the branch you want to merge in with the main trunk (or type it in if it's not in the drop-down list). Click OK.
3. It'll do the merge, but watch the console. It will tell you if any of the files on which it performed a merge had problems. If so, go to those files. In the explorer window on the right you'll see a big red "C" on conflict files. Go edit them, look for the >>>> inside, and fix any problems.
4. Once you've dealt with any conflicts (if there are any), do a test compile. If everything checks out, commit your changes and it will make the appropriate changes to the main trunk.

Basic etiquette.

• Never check-in uncompilable sources. Always do a test compilation before check-in.
• Try to avoid checking in untested (or badly tested) changes.
• Always do an update before a check-in. If any conflicts were born - solve them and make a test compilation.
• If you do some conceptual changes, make a new branch for your sources. You can merge it with the mainstream later when you have all the changes properly tested.
• To be continued...