How to create and manage SourceForge projects

Forge.jpgBy Mike Jackson.

SourceForge is a free and well-established open-source project repository. It currently hosts over 430,000 open-source projects and is used by over 3.7 million registered users. 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 tools for open-source development and community engagement.

  • Source code repository
    SourceForge allows you to store your project's source code under revision control. SourceForge can provide you with a Git, Mercurial, or Subversion repository.
  • File space
    This is used to store project-related materials such as source and binary release bundles, documentation not suited for a wiki (e.g. user or API documentation in HTML form) and any files you don't want to hold under revision control.
  • Web pages
    You can set up web pages to describe your project - SourceForge can host your web site for you.
  • Wiki
    Wikis can be used for documentation. They often have a role similar to web pages, but are quicker and easier to put together and are useful recording information about a project that you edit more frequently than web pages e.g. FAQs, how-tos and information for users and developers.
  • 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.
  • MySQL database
    For use by resources hosted within your project file space.
  • 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.

A note about Allura

In 2012, SourceForge deprecated their support for the TRAC wiki and ticketing system and Wordpress blog, amongst other of what were called "hosted apps" and rolled out their new platform, Allura which has an integrated wiki and ticketing system. The following information applies to the Allura platform.

Conditions on hosted projects

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 terms of use are also placed on projects, for example, you must grant Slashdot Media and Dice 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 Join.
  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. Click Log in and log in.
  3. Click the Create link in "Find, Create, and Publish Open Source software for free" then click Create Your Project Now OR click Me and select Profile then click Add Projects.
  4. Enter a project name e.g. My Project. You may find it useful to see our guide on choosing project and product names.
  5. Enter a URL e.g. myproject. This determines your SourceForge URL e.g. http://sourceforge.net/projects/myproject.
  6. Select your initial set of tools e.g. forums, blog, wiki, tickets, and your preferred revision control tool e.g. Git or Subversion.
  7. Likewise deselect any tools you don't want - 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 tool, you can always set it up later.
  8. Read and accept the Terms of Use.
  9. Click Create.

SourceForge will automatically create for you a project site available via a URL determined by your project name, e.g. http://sourceforge.net/projects/myproject.

When your project has been created you can administer your project via the Admin interface:

  1. Visit your project front page e.g. http://sourceforge.net/projects/myproject.
  2. Click Admin.

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, click the Categorization option under the Admin tab.

It may be worth changing the Export Control settings if applicable, which can be accessed via the Metadata option under the Admin tab. This indicates whether your software includes code for encryption and whether your project is subject to US Export Administration Regulations.

Add a logo

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

  1. Select the Metadata option under the Admin tab.
  2. Click the pen icon under the Icon heading.
  3. Click Choose File and select your logo.
  4. Click Save.

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. Select the Screenshots option under the Admin tab.
  2. Click Choose File and select one of your screenshots.
  3. Enter a caption.
  4. Click Upload.

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. You can also reorder the images by dragging them.

Choose your tools

SourceForge offers a wealth of tools to support your project.

To view the tools available, click the Tools option under the Admin tab.

To enable an available tool listed under Click to install, just click on the tool name.

Manage project members

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

Add a project member

  1. Ask your user or developer for their SourceForge user name.
  2. Select the User Permissions option under the Admin tab.
  3. Choose what type of user the new member is to be e.g. an Admin, a Developer or a Member - this will determine what permissions they have.
  4. Click +Add under the relevant group.
  5. Enter the user name and click Save.

Change a project member's permissions e.g. create a new administrator

To change a user's permissions:

  1. Select the User Permissions option under the Admin tab.
  2. Select the new group to which the member is to be added.
  3. Click +Add under this group.
  4. Enter the user name and click Save.
  5. In the user's previous group, click the "-" next to the user's name.

Change user permissions

For many SourceForge tools you can control what types of user (e.g. Admin, Developer, Member, Authenticated SourceForge user and Anonymous SourceForge user) can do what actions with each tool e.g. who can configure an e-mail list, who can read an e-mail list, or who can read from or write to a source code repository.

To change the permissions of a tool:

  1. Select the Tools option under the Admin tab.
  2. Click Permissions under the tool whose permissions you want to edit.
  3. EITHER Click Add+ under one of the shown actions to add a group to the groups who are allowed to carry out that action.
  4. OR Click "-" under one of the shown actions to remove a group from the groups that are allowed to carry out that action.

For the Files tool there is no Permissions option, instead you use the Release Technicians option.

Create an e-mail list

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

  1. Select the Tools option under the Admin tab.
  2. If Mailing Lists is not under the Installed tools section then click Mailing Lists in the Click to install section to enable mailing lists.
  3. Select the Admin Mailing Lists option under Mailing Lists in the Installed tools section.
  4. Scroll down to New List.
  5. Enter a new list name. You fill in a template so your e-mail list has form myproject-LISTNAME@lists.sourceforge.net e.g. substituting "users" for LISTNAME gives myproject-users@lists.sourceforge.net.
  6. You can also choose whether the e-mail list is public or for members of your project only.
  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. Select the Tools option under the Admin tab.
  2. Select the Admin Mailing Lists option under Mailing Lists in the Installed tools section.
  3. Click Change Password under the list whose password you want to change.

Add a new list administrator

  1. Visit the list administrator's web page e.g. https://lists.sourceforge.net/lists/admin/myproject-LISTNAME.
  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 e.g. https://lists.sourceforge.net/lists/admin/myproject-LISTNAME.
  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 ticketing system

One of SourceForge's features is a ticketing system. This can be used to manage your tasks and bugs.

To enable the ticketing system,

  1. Select the Tools option under the Admin tab.
  2. If Tickets is not under the Installed tools section then click Tickets in the Click to install section.

Update milestones

A new ticketing system will have example milestones and version numbers. You can edit these as follows:

  1. Click Tickets on your project's front page.
  2. Click Edit Milestones in the list on the left of the page.
  3. Click the edit pen icon on the right-hand side of the milestone you wish to edit.

To add a milestone:

  1. Click Tickets on your project's front page.
  2. Click Edit Milestones in the list on the left of the page.
  3. Click Add Milestone.
  4. Enter a name, summary, and due-date.
  5. Click Save.

Create a wiki

One of SourceForge's features is a wiki. This can be used to provide documentation about your project and software.

To enable the wiki,

  1. Select the Tools option under the Admin tab.
  2. If Wiki is not under the Installed tools section then click Wiki in the Click to install section.

Prevent rogue users from editing your wiki

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

  1. Follow the instructions to Change user permissions for your wiki as described above.
  2. Make sure that only project Admin, Developer and Member groups have CREATE, DELETE or EDIT permissions i.e. not any *authenticated users.

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 or that you explicitly want available via this link. Default downloads can be made operating system-specific - the file offered via the Download button being dependent upon the operating system of the user viewing the front-page.

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

  1. Click Files.
  2. Browse through the folders until you find your preferred file.
  3. Click the View details "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, if you want the file to be the default download for all operating systems, click Select All. Otherwise, select the operating systems for which you want this file to be the default.
  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@web.sourceforge.net

2. Get the path to the current directory:

$ pwd /home/project-web/myproject

3. Change into your project's file space. The path is similar to that shown in the last step, but prefixed by /home/pfs 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, the one you ran SFTP in:

$ 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 Doxygen or 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@web.sourceforge.net

2. Change into the htdocs directory

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

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

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

$ mkdir somepages

4. 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 

5. 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

6. 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

$ scp mydocs.zip myuser@web.sourceforge.net:/home/project-web/myproject/htdocs

2. Log in to the SourceForge shell:

$ ssh -t myuser,myproject@shell.sourceforge.net create
myuser,myproject@shell.sourceforge.net's password:

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

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/

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's Allura platform does not allow new SourceForge projects to use CVS. They recommend more modern source code repositories such as Subversion, Git or Mercurial.

Import an existing CVS repository into SourceForge

SourceForge's Allura platform does not allow new SourceForge projects to use CVS. They recommend more modern source code repositories such as Subversion, Git or Mercurial.

If you have a CVS repository you can convert it to Subversion or Git using, for example by using Tigris's cvs2svn which can convert to both Subversion and Git.

You can then import your Subversion or Git repository into SourceForge:

  1. Select the Tools option under the Admin tab.
  2. If your preferred revision control tool (e.g. Subversion or Git) is not under the Installed tools section then click it in the Click to install section to enable it.
  3. Select the Import Repo option under your revision control tool name in the Installed tools section. If you already have a repository, you will be asked to delete the tool, via the Delete link for that tool on the Tools page, then to re-install the tool using Click to install.​

Get notifications from your source code repository

SourceForge can notify you when there are changes to the source code repository:

  1. Click Me.
  2. Select Account.
  3. Click Subscriptions.
  4. Scroll down to myproject code entry and check the box.
  5. Scroll down and click Save.

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. To request a project be removed, Create a Ticket requesting this.

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. For most of these you will need a Linux operating system.

Back up your repository

You can back up your source code via an rsync command. Here are examples for Subversion, Mercurial and Git repositories,

	 
$ rsync -av svn.code.sf.net::p/myproject/code .
$ rsync -av hg.code.sf.net::p/myproject/code .
$ rsync -av git.code.sf.net::p/myproject/code.git .

For more information see the SourceForge documentation on backing up Subversion, Mercurial and Git.

Back up your release files

You can back up your release files via an rsync command.

$ rsync -avP --rsh="ssh -l myuser" frs.sourceforge.net:/home/frs/project/myproject/ files-backup

You will need to enter your password.

Back up your e-mail archives

Back up your email archives via a curl command. For this you will need curl 7.15 or later (to see your version, do "curl --version").

$ curl -k --user myuser:mypassword -o myproject-list.mbox https://lists.sourceforge.net/mbox/myproject-list

For example:

$ curl -k --user myuser:12345678 -o ogsa-dai-users.mbox https://lists.sourceforge.net/mbox/ogsa-dai-users

Back up your web pages

You can back up your source code via an rsync command.

$ rsync -avP --rsh="ssh -l myuser" web.sourceforge.net:/home/project-web/myproject/ project-web-backup

You will need to enter your password.

Back up your databases

If you are using SourceForge's MySQL database you can back these up using their shell and rsync:

Create a shell,

$ ssh myuser,myproject@shell.sourceforge.net create

Send a command to back up your database,

$ ssh myuser,myproject@shell.sourceforge.net "mysqldump -h DATABASE_HOST -u ADMIN_USER -p --opt DATABASE_NAME --password=ADMIN_PASSWORD" > database.sql

Your database host name, admin username and password can be found by going to your project's page on SourceForge, clicking Admin, selecting Tools and clicking Admin MySQL Databases under the MySQL icon.

For example, here is the command to back up OGSA-DAI's blog database,

$ ssh myuser,ogsa-dai@shell.sourceforge.net "mysqldump -h mysql-o -u o261620admin -p --opt o261620_wp --password=12345678" > database.sql

Send a command to shutdown the shell,

$ ssh myuser,myproject@shell.sourceforge.net shutdown

Automating back ups

Some of the above commands need you to enter your password. Using a public/private keypair allows you to avoid this and so bundle the above commands into a script to automatically run your back ups.

On the server from which you want to run your back up commands, create a public and private keypair:

$ ssh-keygen -t dsa -C "myser@shell.sf.net"

When asked for a passphrase, press return.

This will create a private key, id_dsa, and a public key, id_dsa.pub, in a .ssh directory.

Log in to SourceForge.

Click Me and select Account.

Click SSH Settings.

Paste contents of your public key file, id_dsa.pub, into the field as a single line e.g.

ssh-dss ttjuhpouhtvhjbu5urt97uhwre8956UING09== myuser@shell.sf.net

Click Save.

You'll need to wait for a short while before SourceForge has configured itself.

Now, you should be able to run one of the rsync commands for backing up your release files or web pages without needing to enter a password.

Further reading