Ever have one of those days where you find yourself staring down all the little tasks that you really should get done but have absolutely no desire to start? Instead, you spend most of the day lying around resting and maybe reading some inconsequential fiction. Today was one of those days for me. Fortunately, I usually "go nocturnal" after such a day and can still get most of the software projects complete. Tonight I'm working on a blog entry I promised a week ago then I'm going to drop into some late night SDM modeling.
A number of people at Microsoft have asked that I'd write a step-by-step guide for creating a project on SourceForge based on my experiences with the Windows Installer XML toolset. So, let's jump right in:
0. Get your Open Source project approved. Work with your business development team and the Shared Source Initiative team to have your project approved to be released as Open Source. It is important to work with your business team because there are many business angles that the typical geek doesn't necessarily think about. Don't just post your code to SourceForge because you think it is a cool idea, that's a great way to end up in some seriously hot water.
1. Create a SourceForge account. This process is very simple and usually takes less than an hour to be good to go.
2. Register your project with SourceForge. This is a multi-step process that can take about twenty minutes to read all of the licensing information and answer all the questions. It will also take a couple days for the project to be approved and created so be sure to leave extra time if you have a deadline for project creation. Finally, be sure to have the following pieces of information ready before going through the registration process. You should have all of these answers from Step 0.
a. Project name. 3 - 15 lowercase alphanumeric characters that are used to uniquely identify your project everywhere. Choose carefully because you'll never be able to change this name once you create your project.
b. Project title. This is a bit more descriptive than the name. For example, "Windows Installer XML (WiX) toolset" is my personal favorite.
c. Short description. 10 - 255 characters of marketing goo that makes your project sound cool.
d. Business justification. 200 characters - 10 KB that explains why your project should exist.
3. Configure Trove categorization. This categorization shows up just under your project's short description and provides a lot of useful metadata about your project. If you don't post this quickly, you'll get a lot of requests to have it filled in when your project gets more popular.
4. Configure the rest of your project. There are many little things you can tweak in your project. Read about each feature (trackers, file releases, forums, mailing lists, etc.) and decide how you want your project run. Personally, I highly suggest creating three mailing lists: "project-users", "project-devs", and "project-commits". The "users" list is where general questions can be sent and answered. The "devs" list is where bug reports, fixes, and new features can be discussed. The "commits" list is where all CVS information is sent for those that want to monitor the continual status of the project. I also turned off the forums for my project because it was time consuming to track the mailing lists and the forums where the essentially the same questions were being asked. I chose to consolidate everything in the mailing lists.
5. Download PuTTY. Since almost all raw project communication with SourceForge is via SSH we need a Windows client that handles that. PuTTY is recommended by SourceForge and has been pretty friendly once I quit trying to be smarter than it was. My suggestion is to just download the .zip file and extract it into a C:\Program Files\PuTTY directory.
6. Generate a SSH key. Those SourceForge steps are pretty good if you just follow them step by step. One of the important pieces to get right is in "step 6" there is a picture that shows the "Public key for pasting.". Be sure to copy the entire block of text in there. Some of the earlier (or later) SourceForge instructions weren't clear that everything (including the funky little "ssh-dss" text and all of the new lines) was important. Oh, and put the SSH keys somewhere you won't lose them. You can re-create keys but life is just easier if you don't have to.
7. Wait. The SourceForge site says that it only takes 10 - 30 minutes for the SSH keys to be updated, but I had a terrifying early late night experience with this when trying to post WiX for the first time. I started late the Saturday night before WiX was to go public and was up until 4:30 AM Sunday morning trying to get SourceForge to recognize my SSH key. I finally went to sleep exhausted, hoping that I would wake up in the morning and everything would just be okay. I was up at 6:30 AM (not a great night of sleep) and magically all my SSH commands were working. I was so relieved.
8. Play with PAGEANT. PAGENT is a cute little tool that simplifies using SSH tools, but isn't terribly discoverable. The SourceForge documentation about this fact is easy to skip over but once you read the docs (hopefully my link helps find them) all should be clear. Before you try to do any SSH communication with SourceForge, be sure PAGEANT is running (you'll see a little computer con with a black hat in your system tray) or SSH commands will fail.
9. Punching through the firewall with PuTTY. One of the trickiest things to get right was how to talk to SourceForge through Microsoft's firewall. There is a short blurb about that topic in the SourceForge documentation, but here's a step by step.
a. Start putty.exe from the location you downloaded it (in my case, C:\Program Files\PuTTY)
b. In the "Session" node of the navigation tree
Host Name: "PROJECTNAME.cvs.sourceforge.net"
c. In the "Connection" node of the navigation tree:
Auto-login username: <your SourceForge account>
d. In the "Connection->Proxy" node of the navigation tree:
Proxy hostname: proxy (or any other Microsoft proxy server)
e. Back to the "Session" node of the navigation tree:
Saved Sessions: "cvs-ssh"
Click "Save" button
Click "Open" button.
Note: You should see an SSH session start up with SourceForge. If you see something that says, "Welcome to cvs1.sourceforge.net" then get disconnected (because SourceForge does not allow direct access to CVS) then you're good to go. If not, go back and make sure you've configured everything above correctly.
10. Download a CVS-client. The first time through this process, I downloaded WinCvs and just used "cvs.exe" from the command-line because the UI is so atrocious (don't even bother booting the UI). I just added the "C:\Program Files\WinCvs 1.3\CVSNT" directory to my PATH and forgot that there was ever a UI for the cvs.exe. Also, TortoiseCVS looked cute but I don't use Explorer for anything. The command-line is where it's at for me. I recently realized it was possible to get CVSNT without WinCvs and that works just as well.
11. Configure CVS-client to talk SSH via PuTTY. It took a little while to finally get cvs.exe talking to SourceForge. Turns out all you need are two simple environment variables. I added these two variables to my user environment (Start -> right click "My Computer" -> Advanced Tab -> Environment Variables button -> top "New" button) so I wouldn't have to remember them all the time:
Note: that you need to replace "PROJECTNAME" above with your project name from Step 2 above. Of course, you'll also want CVS_RSH to point at your copy of plink.exe that should be found wherever you extracted PuTTY in Step 5 above. Finally, the string "cvs-ssh" is tied back to the "Saved Sessions" entry in Step 9 above. Those strings must match for PuTTY to connect all the dots.
12. Import your license into CVS. My suggestion is that your first check-in to CVS be a copy of the license you're using for your project. This is a really safe way to get started with CVS. So create a directory where you want your project to be stored and put the license text file and only the license text file in that directory. In my case, I created a new directory for my project called "wix_public" and copied the CPL license into a CPL.TXT file there. Then you should be ready to do your first submission to SourceForge:
cvs import -m "Initial license import." projectname Microsoft start
Note: that you should be in the directory that contains only the license text file when you execute this command, so you'll need to replace "projectdirectory" with the correct directory (in my case, "wix_public"). You'll also want to change "projectname" to the name of your project.
13. (optional) Checkout a copy of your CVS configuration (CVSROOT). This step is optional but will enable you to do the advanced configuration of your CVS repository in the following steps. I highly suggest reading all of the SourceForge documentation about these advanced topics before continuing. I personally like to check out CVSROOT to a directory named "projectname_cvsroot" right next to your project. To do so, just enter the following command from the directory that contains your project directory:
cvs co -d projectname_cvsroot CVSROOT
14. (optional) Send mail on all commits. This is an optional configuration step, but I highly recommend it. The SourceForge documentation is pretty good, so I'd suggest just following it step by step.
15. (optional) Configuring granular ACLs on your project. I highly suggest reading this topic and decide if this applies to your project. I decided to enable the cvs_acls script because I wanted to have developers that could do documentation and project maintenance and still be able to review all changes before modifying the source code. It's up to you.
16. Add your files to CVS. While you can have all of your files added during the import in Step 12, I highly suggest adding them by hand (after loading the license text) the first time you go through the process. Also, if you have any binary files be sure to read the SourceForge documentation about the "cvs -kb" switch. Oh and for those of you who are used to Source Depot, CVS requires you to add directories before you can add files to the directories.
17. Wait. Somewhere SourceForge mentions that it can take a couple hours for your changes to CVS to propagate to the anonymous CVS servers that the Web based UI reads from. So, don't worry if your changes aren't showing up through the Web UI for a while. When I was posting the WiX toolset the Monday morning it was to go live, I was sitting around from 4:30 AM to about 6:30 AM waiting for all the CVS servers to catch up. Fortunately, I had already had my scare with the SSH keys in Step 7 and was pretty sure SourceForge would just "Do The Right Thing" (tm). So, over those two hours waiting, I drafted the blog entry that announced the WiX project.
That's it. Hopefully, this blog entry will help those of you taking care of projects that will follow WiX and WTL onto SourceForge. Have fun with it!