Creating and managing SourceForge projects

Forge.jpgBy Mike Jackson.

SourceForge is a free and well-established open-source project repository. It currently hosts over a quarter of a million open-source projects and is used by over 2.7 million developers. In this guide, we'll provide an overview of SourceForge and a how-to for common SourceForge tasks.

Why write this guide?

Creating and managing SourceForge projects is a subject on which we receive a lot of questions. It's also a subject in which we have a lot of experience, so it seemed like a good idea to make this experience generally available.

What do you get?

SourceForge provides a project with myriad resources for open-source development and community engagement.

  • Source code repository
    The fundamental function of SourceForge is to provide somewhere to store your project's source code
  • File space
    This is used to store project-related materials such as binaries and documentation.
  • Web pages
    You can set up web pages to describe your project.
  • Wiki
    Wikis can be used for most dissemination functions. They often have a role similar to web pages, but are quicker and easier to put together.
  • Forums
    Forums provide a publicly available area where you and your users can discuss your project
  • Email lists
    Mailing lists are generally used for project announcements and discussions.
  • Blog
    Blogs provide an informal route for interacting with your community. It's your chance to describe what's going on in your project, the problems that crop up, what you had for breakfast - pretty much anything.
  • Statistics
    Statistics allow you to monitor the uptake of your project, by recording metrics such as downloads and the number of commits to your source code.
  • Ticketing system
    A ticketing system is used to register issues and assign effort to understand or resolve them. They're generally used for bug tracking or dealing with support queries.

Conditions

SourceForge places two primary conditions on the projects that it hosts.

  1. The software must be open source.
  2. The software's licence must be either compliant with the Open Source Initiative's Open Source Definition or be certified as an OSI-Approved Licence.

Other conditions are also placed on projects, for example, you must grant Geeknet Inc (SourceForge's owners) various rights to create derivative works from your software, and you must undertake not to violate third-party copyright or licencing.

Conventions

The examples in this guide will use the project name myproject and the user myuser who has the password mypassword. Substitute your own project name, user and password where these occur.

Set up a SourceForge account

Before you can create a project on SourceForge, you'll need an account:

  1. Visit SourceForge
  2. Click Create Account
  3. Enter your name, email address and select a user name. You'll be warned if your user name is already taken.

Create a project

  1. Visit SourceForge
  2. Log in
  3. Click Account
  4. Click Projects
  5. Click Register a new project
  6. Enter a project name e.g. My Project. You may find it useful to see our guide on choosing project and product names
  7. Enter a URL e.g. myproject. This determines your SourceForge URL e.g. http://sourceforge.net/projects/myproject
  8. Enter a description, a simple summary of your project

You will end up with a project site hosted at a URL determined by your project name, e.g. http://sourceforge.net/projects/myproject.

When your project has been created you can edit the above information and provide more information:

  1. Visit your project front page e.g. http://sourceforge.net/projects/myproject
  2. Move the mouse pointer over Project Admin
  3. Click Settings

It may be worth changing the export control settings if applicable. This indicates whether your software includes code for encryption.

You may find it useful to note down your project group ID. You can get this ID by visiting the Settings page as above then noting down the number that appears in as the group_id value in the page URL e.g. for http://sourceforge.net/project/admin/public_info.php?group_id=123456, its 123456.

The following sections tell you how to enable various SourceForge features you find useful.

Choose your features

SourceForge offers a wealth of features to support your project. In the following sections we describe how to configure many of these. SourceForge has many features enabled by default.

It's a good idea to disable any you don't intend to use - it's no fun for potential or actual users to click on various links only to discover empty blogs, wikis or forums. Don't worry if you're not sure about whether you'll need a feature, you can always enable it again later.

To view the features available:

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Enabled Features to see those currently enabled.
  4. Click Available Features to see all those that you can use.

To enable an available feature:

  1. Click Available Features
  2. Click the box by the feature you want
  3. The feature will disappear
  4. Click Enabled Features
  5. You will see the feature in the list
  6. If this is the first time you've enabled the feature there may be a small delay and the feature will be marked as Pending while SourceForge initialises it

To disable an enabled feature:

  1. Click Enabled Features
  2. Click the box by the feature you want to disable
  3. The feature will disappear but don't worry, SourceForge retains any existing data if you've been using the feature for a while
  4. Click Available Features
  5. You will see the feature in the list

Help people find your project

SourceForge allows you to specify information about your project which helps people to find it using the SourceForge search tools. This includes your research domain, intended users, programming language, operating system and licence. To configure this information:

  1. Move the mouse pointer over Project Admin
  2. Click Settings
  3. Click Edit Trove Categorization
  4. You can then select and enter information about your project and product

Tell users how to ask for help

If users click on Support on the front page of your project they'll get a message telling them how you'd like them to ask for help. This can be by sending an e-mail, creating a TRAC ticket or using a forum. For example:

MyProject says the best way to get help with its software is by sending
email to its mailing list at myproject-users [at] lists [dot] sourceforge [dot] net.

To set how you'd like users to ask for help:

  1. Move the mouse pointer over Project Admin
  2. Click Settings
  3. Click Set Preferred Support Mechanism
  4. SourceForge then allows you to select your preference from any of the publicly-available resources you have (e.g. e-mails) or to contact the project admins directly, or visit a URL. 
  5. When you've selected one click Set Preferred Support Mechanism

Add a logo

If you have one, you can add your project logo to your SourceForge pages. To add a logo:

  1. Visit the front page of your project
  2. Click the Edit link above the dummy logo
  3. Click Browse... and select your logo
  4. Click Save icon

Logos can be PNG, JPEG or GIF images of up to 1MB. They will be rescaled to 48x48 resolution.

Add screen shots

If your software has an impressive graphical user interface then you can upload screen shots that SourceForge visitors can browse.

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Enabled Features
  4. Next to Screenshots, select Manage

You can upload up to 6 screen shots. These can be JPG, PNG or GIF images of up to 300KB size. They must be between 150x150 and 640x480 resolution. Anything larger is rescaled to 640x480.

Manage project members

As a project administrator, you have extensive control over who is a member of your project and what they can do. To become a project member, your users or developers must sign up for a SourceForge account.

Add a project member

  1. Ask your user or developer for their SourceForge user name
  2. Move the mouse pointer over Project Admin
  3. Click Members
  4. Enter the user name in the Add a new member to the project field
  5. Click Add member

Edit a project members permissions e.g. creating a new administrator

To edit a user's permissions:

  1. Move the mouse pointer over Project Admin
  2. Click Members
  3. Click on the user's name

You can then:

  • Make the user a project administrator
  • Allow them to access the shell server group space
  • Allow them to access the Subversion repository
  • Note them as a release technician

You can also select their role for various tools supported by your project. This dictates whether they can configure and/or use these tools.

  • Tracker Manager - can set a user to be an Admin
  • Task Manager - can set a user to be one of a Technician, Admin & Tech, or Admin
  • Forums - can set a user to be a Moderator
  • Project News - can set a user to be an Editor
  • Screenshots - can set a user to be an Editor
  • Role - this is for information only as to what the member does in the project

Create an e-mail list

You can create any number of e-mail lists for your project. To create an e-mail list:

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Manage on the Mailing Lists table entry.
  4. Scroll down to Add a Mailing List
  5. Enter a new list name. You fill in a template so your e-mail list has form myproject-XXXX [at] lists [dot] sourceforge [dot] net e.g. substituting users for XXXX gives myproject-users [at] lists [dot] sourceforge [dot] net
  6. You can also choose whether the e-mail list is public or for members of your project
  7. Click Create to create your mailing list
  8. You will be sent an administrator password for your mailing list and a link to the administrator's web pages. For the above, the URL would look like https://lists.sourceforge.net/lists/admin/myproject-users.

Change the list administrator password

  1. Visiting the list administrator's web page
  2. Click on the Passwords link at the top left of the page.
  3. Follow the instructions on screen

Add a new list administrator

  1. Visit the list administrator's web page
  2. Click on the General Options link at the top left of the page
  3. Add the new list administrator's e-mail address to The list administrator email addresses field in the second row of the table.
  4. Scroll to the bottom of the page
  5. Click Submit Your Changes

Specify how subscriptions are handled

  1. Visit the list administrator's web page
  2. Click on the Privacy options... link at the top left of the page, in the second column of links
  3. Click on the Subscription rules link
  4. Scroll down to the second row of the table
  5. Select your choice: Confirm - a new member just confirms membership by clicking an auto-generated link; Require approval - new member requests are held, you are notified and you click on a link to authorise their membership; Confirm and approve - a combination of the above.
  6. Click Submit Your Changes

Create a TRAC wiki and ticketing system

One of SourceForge's features is TRAC which combines a wiki with a ticketing system. This can be used to manage both your project documentation and your tasks and bugs.

To enable TRAC, set it up as a feature as described above.

To visit the TRAC admin page you can

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Manage on the TRAC table entry.

OR

Visit the TRAC admin page directly. This has a URL of form:
https://sourceforge.net/apps/trac/myproject/admin

You can remove from the TRAC menu bar any views you don't want/need:

  1. Click Permissions
  2. In the anonymous row click any views you don't want/need e.g. MILESTONE_VIEW, ROADMAP_VIEW, TIMELINE_VIEW etc.
  3. Click Remove selected items
  4. If you need them later you can use the Grant Permissions box at the right of the page to re-add them

Update milestones

A new TRAC will have example milestones and version numbers. You can edit or remove these as follows:

  1. Visit the TRAC admin page
  2. Click Milestones under the Ticket System heading in the list on the left of the page
  3. To remove a milestone, select the box to its left and click Remove selected items
  4. To edit a milestone, click on its name
  5. To add a milestone, enter its name and due date in the Add Milestone box on the right of the page and click Add

Add a new a TRAC administrator

  1. Visit the TRAC admin page
  2. Click Permissions
  3. Look at the Grant Permission box on the right of the page
  4. Enter the user's SourceForge username in the Subject field
  5. Select TRAC_ADMIN from the list in the Action field
  6. Click Add

Prevent rogue users from editing your TRAC wiki

SourceForge allows any SourceForge user to edit the TRAC wiki. This can (rarely) lead to spammers adding adverts. To restrict access:

  1. Visit the TRAC admin page
  2. Click Permissions
  3. Look at the Grant Permission box on the right of the page
  4. Enter your project name in the Subject field
  5. Select WIKI_CREATE from the list in the Action field
  6. Click Add
  7. This creates a new group to allow you get more control over permissions.
  8. Enter your project name in the Subject field
  9. Select WIKI_MODIFY from the list in the Action field
  10. Click Add
  11. Look at the Manage Permissions table in the centre of the page
  12. Click the WIKI_CREATE box in the authenticated row
  13. Click the WIKI_MODIFY box in the authenticated row
  14. Scroll down
  15. Click Remove selected items
  16. Then, for each user in your project use the Add Subject to Group area to associate them with the project by entering their user name in the Subject field and the project name in the Group field, then clicking Add

If you use this approach you'll have to remember that, if you get new project members, to add them to your project group using the Add Subject to Group area.

Upload release files

When users visit your front-page at http://sourceforge.net/projects/myproject they'll see a download link for your most recent release. There's also a Files link, which takes users to a directory structure from which all your past and present release bundles can be downloaded.

Before a user can download anything, you'll have to upload some files. There are a number ways of uploading files, so we'll cover the two most common ways in this guide.

An important note about the Download button

The upload order determines which file is exposed as the Download button on your project's front-page. The most recently uploaded file is always exposed first, so some consideration is need to ensure that the file connected to the highly visible Download link is the file that you upload last.

If the wrong file is connected to Download, you can change it by:

  1. Click Files
  2. Browse through the folders until you find your preferred file
  3. Click the "i" icon at the right of the file's entry in the table of files
  4. In the pop-up window, under the Default download for: heading, click Select All
  5. Press Save
  6. Give it a few minutes, refresh your project page and check the link

Upload via an internet browser

After you've logged in to SourceForge:

  1. Visit http://sourceforge.net/projects/myproject
  2. Click Files

Your browser will show a directory structure and the following commands will be available:

  • Add File
  • Add Folder

Choose Add File to select and upload a file for release.

Upload via SFTP on Linux/UNIX

Rather than using the browser interface, you can also log into SourceForge and transfer files using secure FTP.

1. Log into the SourceForge SFTP server:

$ sftp myuser,myproject [at] web [dot] sourceforge [dot] net

2. Get the path to the current directory:

$ pwd
/home/project-web/m/my/myproject

3. Change into your project's file space. The path is similar to that shown in the last step, but prefixed by /home/pfg rather than /home/groups:

$ cd /home/pfs/project/m/my/myproject

You are now at the root of the directory structure exposed via the web interface above.

4. You can make new directories using the command:

$ mkdir Release1.2.3

And change into these using the command:

$ cd Release1.2.3

5. If you'd run SFTP from a directory which contained the files release1.2.3-src.zip and release1.2.3-bin.zip, you could upload these to SourceForge:

$ put *zip
$ ls
release1.2.3-src.zip release1.2.3-bin.zip

6. Use lls to list the files in your local directory

$ lls
release1.2.3-src.zip release1.2.3-bin.zip

7. If the files were in another directory on your local server, just provide the full path:

$ put /home/user/mylocal/releases/*zip

8. It's useful if you now change the permissions of any new directories you create or files you upload so that any project member is allowed to to change and update them:

$ cd ..
$ chmod 0775 Release1.2.3
$ chmod 0775 Release1.2.3/*

Upload web pages

If you've selected the web pages feature, then SourceForge will provide you with an area for hosting web pages. This allows you to host HTML content, expose JavaDoc API documentation or create an informative and enticing entry point for your project. The front page URL will be of the form http://myproject.sourceforge.net (for example, see http://ogsa-dai.sourceforge.net/).

You can log into SourceForge and upload web pages using secure FTP:

1. Log into the SourceForge SFTP server:

$ sftp myuser,myproject [at] web [dot] sourceforge [dot] net

2. Get the path to the current directory e.g.

$ pwd
/home/project-web/m/my/myproject

3. Change into the htdocs directory

$ cd htdocs

You are now at the root of the directory structure exposed via the your front-page URL.

4. You can make new directories into which you can upload web pages using:

$ mkdir somepages

5. Change into the new directory using:

$ cd somepages

Now, if you're running SFTP from a directory which contained the file mypage.html, you could upload this to SourceForge using put:

$ put mypage.html
$ ls
mypage.html

6. You can use lls to list the files in your local directory:

$ lls
mypage.html myotherpage.html

If the files were in another directory on your local server then just provide the full path:

$ put /home/user/mylocal/html/mypage.html

7. It's useful if you now change the permissions of any new directories you create or files you upload so that any project member is allowed to to change and update them:

$ cd ..
$ chmod 0775 somepages
$ chmod 0775 somepages/*

Bulk loading files and web pages

If you have a lot of files or web pages, it's quicker to bundle them into a ZIP file, upload the ZIP to SourceForge and then extract the files from the ZIP file:

1. First of all, upload the ZIP file

$ put mydocs.zip

2. Log in to the SourceForge shell:

$ ssh -t myuser,myproject [at] shell [dot] sourceforge [dot] net create
myuser,myproject [at] shell [dot] sourceforge [dot] net's password:

Requesting a new shell for "myuser" and waiting for it to start.
queued... starting...

This is an interactive shell created for user myuser,myproject.
Use the "timeleft" command to see how much time remains before shutdown.
Use the "shutdown" command to destroy the shell before the time limit.
For path information and login help, type "sf-help".

3. Change into the directory where you saved your ZIPs:

$ cd /home/project-web/myproject/htdocs/somedocs

4. Unzip the ZIP:

$ unzip mydocs.zip

Upload documents

There are a number of options for hosting documents, such as Microsoft Word or PDF documents. The option you choose depends on factors such as the role of the document, who you intend to access it, and who is allowed to update it. Documentation, for example, might be attached to a web page so it could be uploaded in the same way as a web page, as described above.

There are four options for hosting documents:

  • Store the document in your source code repository
  • Attach the document to a wiki page (beware of the limit on attachment size, which is 256K)
  • Load the document into your web space, as for web pages
  • Load the document into your file space, as for releases

Create a CVS repository in SourceForge

SourceForge recommends that projects do not use CVS, since they prefer more modern source code repositories such as SVN or Git. However, SourceForge does support CVS for users who find it adequate for their needs or have a CVS legacy archive.

To create a CVS repository for your project:

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Available Features
  4. Check the Enabled box to left of the CVS row
  5. Wait a few minutes
  6. Browse to http://sourceforge.net/projects/myproject
  7. Move the mouse pointer over Code
  8. You should see entries for CVS, CVS Browse and CVS Statistics

Import an existing CVS repository into SourceForge

In the following section, we describe how to import an existing CVS repository. Be warned that this process assumes that you have not used your CVS repository in SourceForge, and are creating a new repository based on a CVS repository exported from elsewhere.

1. First, ZIP up the CVS repository, e.g. if you have a repository in cvs

$ ls cvs
CVSROOT directoryone directorytwo
$ zip -r cvsrepository.zip cvs

2. Upload the zip to SourceForge:

$ sftp myuser,myproject [at] web [dot] sourceforge [dot] net
$ pwd
/home/groups/m/my/myproject
$ put cvsrepository.zip

3. Login to the SourceForge shell:

$ ssh -t myuser,myproject [at] shell [dot] sourceforge [dot] net create

4. Lock your SourceForge CVS repository:

$ adminrepo --checkout cvs
Lock and checkout the cvs repository for myproject? [ny] y

5. The previous step provides you with your repository in /cvsroot, which you can check:

$ ls /cvsroot
myproject

6. Copy the ZIP to /cvsroot/myproject

$ mv cvsrepository.zip /cvsroot/myproject/

7. Change to /cvsroot/myproject and delete its current content:

$ cd /cvsroot/myproject
$ rm -rf *

8. Now unZIP your repository:

$ unzip cvsrepository.zip
$ ls
cvs cvsrepository.zip

9. Move the content out of the unZIPped sub-directory:

$ mv cvs/* .

10. Clean up!

$ rm cvsrepository.zip
$ rmdir cvs

11. You'll be left with the CVS repository files:

$ pwd
/cvsroot/myproject
$ ls
CVSROOT directoryone directorytwo

12. Now exit the /cvsroot/myproject directory and commit the changes:

$ cd
$ adminrepo --save

13. Now, on your project front page, move the mouse pointer over Code, select CVS Browse, and you should be able to navigate through your CVS and see the history of changes, etc.

Get emails from your source code repository

If you are using a source code repository in SourceForge, you can configure it to email an address every time a repository commit is made. This can be useful for keeping developers and other interested parties up-to-date on changes to the code. It's a good idea to create a dedicated email list for this purpose, such as myproject-source-commits, and then encourage developers to subscribe to the list.

Get emails from SVN

You can turn on emailing of commit messages by:

  1. Move the mouse pointer over Project Admin
  2. Select Features
  3. In the Subversion row, click Manage
  4. From the Hooks drop-down list, select either svnnotify - Send commit notification e-mail or svnnotify - Send commit notification e-mail w/o diffs included"
  5. Click Add
  6. Enter the email address you would like to use, for example myproject-source-commits [at] lists [dot] sourceforge [dot] net.
  7. Click Finish Add

Any of your project members who use SVN need to be subscribed to the e-mail list that you use otherwise their commit e-mails will bounce (though their commits will be made).

Get emails from CVS

1. To set up CVS emailing, you need to check out your CVS root:

$ cvs -z3 -d:ext:myuser [at] myproject [dot] cvs [dot] sourceforge [dot] net:/cvsroot/myproject co -P CVSROOT

2. Then edit the CVSROOT/loginfo file and add the lines:

# This line sends all changes to the CVSROOT module to the user specified
# by USERNAME. It is recommended that someone be watching this module
# as it shouldn't need to be modified very often.
CVSROOT /cvsroot/sitedocs/CVSROOT/cvstools/syncmail %{sVv} USERNAME [at] users [dot] sourceforge [dot] net
# This sends mail to a mailing list, defined by the PROJECTNAME-LISTNAME
# value. Any changes to any modules in the project will thus generate an
# email message to the mailing list specified.
DEFAULT /cvsroot/sitedocs/CVSROOT/cvstools/syncmail %{sVv} EMAIL

replacing USERNAME with your SourceForge user name and EMAIL with the email to receive the messages:

CVSROOT /cvsroot/sitedocs/CVSROOT/cvstools/syncmail %{sVv} myuser [at] users [dot] sourceforge [dot] net
DEFAULT /cvsroot/sitedocs/CVSROOT/cvstools/syncmail %{sVv} myproject-source-commits [at] lists [dot] sourceforge [dot] net

3. Now commit the changed file:

$ cvs commit -m "Added e-mail recipients" loginfo

Remove a project

SourceForge has strict conditions about removing projects. Conditions are attached to the removal. A project will not be removed within 90 days of creation, it will not be removed if the project has released any files, and it will not be removed just because its members want to close the source code.

Back up SourceForge

It is highly recommended that you back up SourceForge, following the old adage than it's always good to have a back up. SourceForge provides support for this.

Back up SourceForge configuration

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Enabled Features
  4. Click on XML Export at the right of the Backups row to download your SourceForge configuration and project information as XML

Back up TRAC

  1. Move the mouse pointer over Project Admin
  2. Click Features
  3. Click Enabled Features
  4. Click on Hosted Apps at the right of the Backups row
  5. Select trac from the Application to backup list
  6. Click Database
  7. Select a compression format
  8. Click Submit Query
  9. Select trac from the Application to backup list
  10. Click Files
  11. Select a compression format
  12. Click Submit Query

Back up e-mail list archives

  1. Visit the URL https://lists.sourceforge.net/mbox/LISTNAME e.g. https://lists.sourceforge.net/mbox/myproject-users
  2. Enter your mailing list administrator username and password.
  3. The archive will be downloaded in a MBOX format.

Note that the URL is only available if your e-mail archive contains at least 1 message.

Back up CVS

Back up your SourceForge CVS via an rsync command:

$ rsync -av rsync://myproject.cvs.sourceforge.net/cvsroot/myproject/* myproject-cvs-backup

Back up SVN

Back up your SourceForge SVN via an rsync command:

$ rsync -av myproject.svn.sourceforge.net::svn/myproject/* myproject-svn-backup -backu--bffffggggg-back,cklccccffffc

Further reading

Last updated: Tuesday 30 August 2011.