FusionForge Manual

Tom Copeland

Roland Mas

Ken McCullagh

Tim Perdue

Guillaume Smet

Reinhard Spisser

1. Introduction
1. About FusionForge
2. FusionForge History
FusionForge Installation Guide
1. Hardware Requirements
2. Software Requirements
3. Installation
3.1. Overview
3.2. Installing FusionForge on Debian
3.3. Installing Gforge on RPM-based systems
3.4. Installing FusionForge oneself on a linux distribution
3.5. Configuring the Database (PostgreSQL)
3.6. Configuring DNS Server (BIND)
3.7. Configuring PHP
3.8. Configuring the Web Server (Apache)
3.9. Configuring Mail Transport Agent (Any)
3.10. File Release System (FRS)
3.11. Configuring GNU Mailman
3.12. Source Code Management (SCM)
3.13. Cron Jobs
3.14. Verifying the Installation
3.15. Creating the Admin User
3.16. Customizing Front Page
3.17. Optional Features
4. Plugins
4.1. CVS
4.2. CVSTracker
4.3. SVN
5. Upgrading Existing Install
6. Most Common Problems
FusionForge Administration Guide
1. Introduction
2. What is FusionForge?
3. What can FusionForge do for me?
4. Setting up a new project
5. Registering a new project
6. Administering a new project
7. CVS repository
8. Setting up the CVSROOT
9. Setting your .rhosts file correctly
10. Creating the CVS repository
FusionForge User Guide
1. Introduction
1.1. Getting Started
1.2. User specific functions
1.3. Project specific functions
1.4. Site-wide functions
2. Getting Started
2.1. FusionForge homepage
2.2. Registering as a new user
2.3. Registering a new project
2.4. Login
2.5. Logout
3. User specific functions
3.1. User Homepage
3.2. Modifying User settings
3.3. Changing the language on FusionForge
3.4. User ratings
3.5. Skills profile
3.6. Diary and Notes
4. Project functions
4.1. Project Summary
4.2. Project Activity
4.3. Project Administration
4.4. Forums
4.5. Tracker
4.6. Mailing Lists
4.7. Task Manager
4.8. Document Manager
4.9. Surveys
4.10. News
4.11. CVS
4.12. File Releases
5. Site-wide functions
5.1. Introduction
5.2. Searching in FusionForge
5.3. Trove map
5.4. Snippet Library
5.5. Project Help
FusionForge Contribution Guide
1. How to contribute
2. FusionForge repository
2.1. Anonymous access
2.2. Modules in repository
3. PHP Coding Standards
3.1. Introduction
3.3. Formatting
3.4. Templating
3.5. Expressions
3.6. Functions
3.7. Objects
3.8. Naming
3.9. Control Structures
3.10. Including PHP Files
4. Templating Standards
4.1. Coding Example
5. Documentation
6. How to obtain XHTML compliance for FusionForge

Chapter 1. Introduction

1. About FusionForge

FusionForge is a software for collaborative development for the software community. It provides a full configured development system with versioning, a project web site and tools for communication between members of a development team. The tools provided by FusionForge allows team members to communicate and organize their work; this allows the creation of a knowledgebase.

A complete configurated FusionForge system will give you the following features:

  1. A Web site for every project

  2. Versioning via CVS or Subversion

  3. Shell access to the server for the developers

  4. A web site for project coordination and comunication between team members:

    1. Discussion Forums - For discussions between team members

    2. Bug tracking - Allow registration and administration of bugs

    3. Support requests, patch submissions, and enhancement requests

    4. Comunication between project members using mailing lists

    5. Sharing of documentation

    6. Handling of todo lists, tasks, etc

    7. File uploads/releases

    8. Posting of news - Every project can have its own news items.

    9. Code Snippets - Provides of a basic knowledgebase that can contain code fragments, HOWTOs, etc.

The tasks and the tracker items (to track bugs, patches, support requests, enhancement requests) can be classified using status, priority, category.

The system provides also a classification system of the projects, a user profile, and a user rating system.

2. FusionForge History

FusionForge is a fork of the 2.61 SourceForge code, which was only available via anonymous CVS from VA (Research|Linux|Software). gforge.org is not a project hosting platform, it is merely an implementation of the FusionForge code. We believe that the FusionForge functionality is important not only to the Open Source community, but to the wider business community.

Since VA has not released the source in over one year, despite their promises to the contrary, a fork was necessary to ensure a viable open source version of the codebase.

The FusionForge project was formed and is maintained by Tim Perdue, the original author of much of the original SourceForge web code.

Major changes are present in the current FusionForge codebase:

  • Jabber Support - System events, such as bug submissions, are optionally sent via jabber and email

  • Radically easier to install - By removing SF.net-specific code, like caching and image servers, many install dependencies have been eliminated.

  • New interface - The interface makes it easier to navigate as well as know your present location.

  • Code cleanup - Since FusionForge does not need to scale to 500,000+ users, many hacks and optimizations have been removed

  • Foundries and related nonsense have been removed

FusionForge Installation Guide

Reinhard Spisser

Tom Copeland

Ognyan Kulev

Guillaume Smet

1. Hardware Requirements

Hardware requirements are dependent on the number of users that will use the system and how active those users are.

For instance, an installation of FusionForge hosts over 450 users and over 140 projects on a single CPU Pentium 2.4GHz machine with 512 MB of RAM.

You can find additionnal information about hardware used by several installations of FusionForge in the FusionForge sites list maintained by Tom Copeland.

2. Software Requirements

FusionForge should work correctly on any system configured like this:

  1. Linux Operating System

  2. PostgreSQL 8.3 or later (8.1, 8.2 should work)

  3. Apache 2.2 or later

  4. openssl 0.9.4 or later

  5. mod_ssl 2.4.10 or later (included in Apache 2.0 and later)

  6. PHP 5.2 or later (php4 with the command line interface support and php5.1 should work)

  7. php-pgsql (enable it with --with-pgsql when building PHP, or install it as package)

  8. php-mbstring (enable it with --with-mbstring when building PHP, or install it as package)

Optional software:

  1. Turck MMCache or PHP Accelerator or any other PHP accelerator (highly recommended)

  2. GNU Mailman and Python (Mailing list support)

  3. Jabberd (Jabber support)

  4. JPGraph (Gantt Charting and Graphing Support)

  5. Perl, DBI module and associated DBD::Pg.

Successful installations and operations have been done using the following systems:

  • Debian GNU/Linux 5.0 (Lenny)

  • CentOS 4 & 5

  • RedHat Enterprise Linux 4 & 5

3. Installation

3.1. Overview


The INSTALL file in FusionForge package and README files in plugin directories are the authoritive sources for installation instructions and they should have more precedence over this guide.


This installation guide is for FusionForge 4.9.

FusionForge has a lot of different pieces touching a lot of different components in the system. Cronjobs are required to maintain the system, touching lots of files on a daily and hourly basis, including /etc/* system files.

The plugins that now manage the CVS and SVN functionality have made installation slightly harder because even more files have to be moved into place during installation.

The manual installation of FusionForge is documented below. Be sure to follow each step carefully, check the forums for frequently asked questions, and ask your Apache, Mailman, and PostgreSQL installation questions in the corresponding mailing lists rather than on the FusionForge forums where little help is available.

3.2. Installing FusionForge on Debian

You can simply add lines found at http://debian.fusionforge.org/ to /etc/apt/sources.list and type apt-get install fusionforge to install a working FusionForge system, thanks to Christian Bayle and Roland Mas.

Note that FusionForge will soon be part of official Debian, and so you will find it in all debian mirrors all other the planet. Package versions of FusionForge may lag behind upstream versions. From scratch install snapshot are also available for a guided installation.

3.3. Installing Gforge on RPM-based systems

RPM should be available soon, see http://fusionforge.org/ website for availability.

3.4. Installing FusionForge oneself on a linux distribution

To install FusionForge, follow these steps (as root):

3.4.1. Directory Layout

Instructions below assume that gforge is unpacked into /opt/gforge . There are some other directories where FusionForge stores files. In this installation guide, they are put in /var/www too.


If you want to be FHS-compliant, FusionForge should be unpacked into /usr/local/share/gforge, and directories for storing files should be in /var/lib/gforge or /var/local/gforge. You may use symbolic links to physically place files in FHS-compliant places and still use directory paths that are presented in this manual.

3.4.2. Getting the source

There is two ways to get the sources from FusionForge :

 # tar -xjvf fusionforge-4.9.tar.bz2
 # cd fusionforge-4.9
 # mkdir -p /opt/gforge
 # cp -r */opt/gforge

3.4.3. Checking out from the SVN repository with tag v4_9

Alternative way to get FusionForge 4.9 is to check out with tag v4_9 from SVN. This gets latest fixes as well.

 $ svn checkout --username anonsvn https://svn.gforge.org/svn/gforge/tags/v4_9

 $ cd gforge/www/plugins
$ ln -s ../../plugins/scmcvs/www scmcvs
$ ln -s ../../plugins/scmsvn/www scmsvn
$ ln -s ../../plugins/cvstracker/www cvstracker Updating checked out Branch_4_5

To get latest updates in Branch_4_5, run the following commands:

$ cd gforge
 $ svn -q update

To monitor latest changes in FusionForge, subscribe to gforge-commits mailing list. Fixing access rights

You may want to make sure that permissions are correct (replace apache-group with the system group used by Apache server):

# cd /opt/gforge
# chown -R root:apache-group .
# chmod -R 644 .
# find -type d | xargs chmod 755
# chmod -R 755 cronjobs

3.4.4. FusionForge Config File

In the FusionForge distribution, you will find etc/local.inc.example. Copy it to /etc/gforge/local.inc and edit all of the settings. In later sections, there is more information about specific configuration settings. Usually, you will want to make it readable only by webserver user (see Section 3.8, “Configuring the Web Server (Apache)” for apache-user and apache-group):

# mkdir /etc/gforge
# chown root: /etc/gforge
# chmod 755 /etc/gforge
# cp /opt/gforge/etc/local.inc.example /etc/gforge/local.inc
# chown apache-user:apache-group /etc/gforge/local.inc
# chmod 600 /etc/gforge/local.inc

3.4.5. Configuring FusionForge

Open /etc/gforge/local.inc, configuring the following basic parameters:

  1. Database configuration:

  2. The directive $sys_default_domain should contain the domain of your server, e.g. gforge.company.com. You may want to replace all occurences of company.com with company's domain name.

3.5. Configuring the Database (PostgreSQL)

3.5.1. PostgreSQL Requirements

You to have installed the following packages for

  1. a CentOS or Red Hat 5 or Fedora: postgresql, postgresql-libs, postgresql-server, postgresql-contrib

  2. a Debian: postgresql, postgresql-contrib

  3. a Red Hat 4 : postgresql, postgresql-contrib

3.5.2. Initialization of PostgreSQL

In some distributions, PostgreSQL database cluster is not initialised. Consult distribution documentation for more information. If database cluster is not created, you can do so by running:

# su - postgres
$ initdb


This will wipe out any existing PostgreSQL databases!

3.5.3. PostgreSQL Authentication Configuration

The postgres PostgreSQL user is used only during installation. Usually, it can connect via UNIX socket without password when invoked by postgresql system account. Check by running this:

# /etc/init.d/postgresql restart
# su - postgres
$ psql template1

If connection fails, add the following line to pg_hba.conf:

local all postgres ident sameuser

FusionForge uses gforge PostgreSQL user to connect to gforge database by using password. (You can change that name by editing local.inc.) In order this to work, assure that you have the following line in your pg_hba.conf (before other host directives):

host gforge gforge md5

This line assumes that FusionForge will always use local PostgreSQL database (localhost). If this is not the case, consult PostgreSQL manual for ways to allow connection.

After all these changes to PostgreSQL configuration files are made, PostgreSQL should be restarted. This depends on the distribution. In Debian, it's like this:

# /etc/init.d/postgresql restart

3.5.4. Importing Database

Create FusionForge database user:

# su - postgres
$ psql template1
template1-# PASSWORD 'gforge-password';

Create FusionForge database:

template1=# \q

Add PL/pgSQL support using the commands:

$ createlang plpgsql gforge

Finally, install the database:

$ cd /opt/gforge/db
$ psql -a -U gforge -W -h localhost -f gforge.sql gforge &> /tmp/gforge.sql.log


You may experience the following errors. They are harmless and you can safely ignore them:

ERROR:  permission denied for language c
ERROR:  must be superuser to create procedural language
ERROR:  permission denied for schema public

3.6. Configuring DNS Server (BIND)

FusionForge needs its own domain. In example FusionForge configuration file, it's gforge.company.com. You should search for company.com in example FusionForge configuration file and replace it with your domain name.

Here some example configuration files for BIND are presented that can help you if you are not familiar with BIND but it's not meant to be complete. Don't ask BIND-related questions in FusionForge forums, consult documentation that come with your distribution and search in Internet. Distributions put files in different places and so there are no file locations here. The example configuration below is only quick start example and doesn't include reverse mapping.

For DNS, you need to have the bind package installed

New subdomain in gforge.company.com should be created. In company.com zone file, it may look like that:

gforge          IN      NS      ns.gforge.company.com.
ns.gforge       IN      A


Do not add the latter resource record (ns.gforge) if this DNS server serves both company.com and gforge.company.com zones.

New zone file for gforge.company.com may look like this:

$TTL    2d
@       IN      SOA     gforge.company.com. hostmaster.gforge.company.com. (
                              1         ; Serial
                         172800         ; Refresh
                            900         ; Update retry
                        2419200         ; Expire
                           3600 )       ; Negative Cache TTL
@               IN      NS      ns.gforge.company.com.
@               IN      A
ns              IN      A

download        IN      A
shell           IN      A
users           IN      A
lists           IN      A
cvs             IN      A
svn             IN      A
scm             IN      A
ldap            IN      A
jabber          IN      A

The new zone must be added in main BIND configuration file:

zone "gforge.company.com" {
        type master;
        file "/dist-specific/path/to/zone-file";

Of course, changes will take effect after reloading BIND.

It is required that the dns service is up on each reboot.

$ chkconfig named on

3.7. Configuring PHP

Make sure you have installed pgsql and mbstring modules.

PHP is used in two ways:

  1. Serving Web pages. In this case, PHP is usually used as module and its configuration is in virtual host configuration, as shown later in the document. If you prefer to configure php.ini, the following directives are required by FusionForge:

    magic_quotes_gpc = On
    file_uploads = On
  2. Cron jobs and some scripts require PHP Command-Line Interface (CLI). Scripts are usually invoked with command like this:

    $ php5 -f cronjobs/mail/mailing_lists_create.php


    The -f is optional when using PHP CLI but it's required when PHP CGI executable is used.

    You must set include_path in PHP CLI php.ini, like already shown above. Increase memory_limit configuration parameter to at least 32M. To find where php.ini is located, use the following command:

    $ php5 -i | fgrep php.ini

3.8. Configuring the Web Server (Apache)

Find what system user and group are used by Apache server and change $sys_apache_user and $sys_apache_group (in FusionForge configuration) respectively in /etc/gforge/local.inc.

You should decide where to put FusionForge configuration of Apache. It's best if own configuration file that is included by main Apache configuration is used. Consult documentation of your distribution on recommended ways for doing this.

You may use etc/gforge-httpd.conf.example as template for your configuration. The rest of the section is guide to making FusionForge virtual host configuration for Apache from scratch. All is inside the following template:


# Put the rest of the directives here.



Configuring for SSL is not discussed in this guide.

  1. Set basic virtual host settings:

    ServerName  gforge.company.com
    ServerAdmin webmaster@gforge.company.com
  2. Define log files:

    CustomLog "/var/log/gforge/gforge/access.log" combined
    ErrorLog  "/var/log/gforge/gforge/error.log"

    Usual practice is to use logrotate on these files. Alternative is to pipe logs to cronolog which will automatically make directory with access.log and error.log for each day:

    CustomLog "|/usr/bin/cronolog /var/log/gforge/gforge/%Y/%m/%d/access.log" combined
    ErrorLog  "|/usr/bin/cronolog /var/log/gforge/gforge/%Y/%m/%d/error.log"


    In FHS-compliant install, you may want to use /var/local/gforge/log instead of /var/log/gforge. In any cases, the relevant directories should be created with appropriate permissions.

  3. Set up document root:

    DocumentRoot "/opt/gforge/www"
    <Directory "/opt/gforge/www">
        Options        FollowSymLinks
        AllowOverride  None
        Order          allow,deny
        Allow from all
        ErrorDocument  404 /404.php
  4. Configuring PHP for Apache

    Ensure that PHP module is loaded (this is automaticaly made when you install php with rpm or deb). You may need to consult your distribution manual. Typical lines that load and configure PHP module are like this:

    LoadModule php_module modules/libphp.so
    AddModule mod_php.c
    AddType application/x-httpd-php .php

    Insert the following instructions after the DocumentRoot directive:

    <Location /projects>
      ForceType application/x-httpd-php
    <Location /users>
      ForceType application/x-httpd-php


    If you use Apache 2, you may need to use a different configuration. Usually, this is not needed. If you receive a Page Not Found summary pages, you better try this different style of configuring.

    Change the existing Files directive to:

    <Files *.php>
        SetOutputFilter PHP
        SetInputFilter PHP
        AcceptPathInfo On
        LimitRequestBody 2097152

    The LimitRequestBody directive allows you to limit the maximum number of bytes of a request (including uploads). The default is 524288 (512Kb). This means that you cannot upload files with a size greater than 512Kb. With this directive, we set it to 2MB. If you wish to set this value higher than 2MB, you must also edit the upload_max_filesize directive in PHP configuration file.

    Add the following lines:

    <Files projects>
    SetOutputFilter PHP
    SetInputFilter PHP
    AcceptPathInfo on
    <Files users>
    SetOutputFilter PHP
    SetInputFilter PHP
    AcceptPathInfo on
  5. Set up PHP module:

    If the register_globals variable is set to On in your php.ini, add this line in your conf apache :

    php_flag   register_globals Off

    If the files_uploads variable is not set to On in your php.ini, add this line in your conf apache :

    php_flag   files_uploads    On

    If the AddDefaultCharset variable is not set to UTF-8 in your httpd.conf, add this line in your conf apache :

    php_value  default_charset  "UTF-8"

    Add these lines in your conf apache

    php_flag   magic_quotes_gpc On
    php_value  include_path     ".:/etc/gforge:/opt/gforge:/opt/gforge/www/include"
  6. Set up directory index script name (this is automaticaly made when you install php with rpm or deb) :

    DirectoryIndex index.php

Of course, all changes will take effect only after reloading or restarting Apache.

3.9. Configuring Mail Transport Agent (Any)

Add the following line to /etc/aliases and run newaliases:

noreply: /dev/null

Make sure that the following domain names are accepted as local destinations by mail transport agent:

  • gforge.company.com

  • lists.gforge.company.com

  • users.gforge.company.com

You may want to consider adding MX (mail exchanger) resource records for the above domain names. This is meaningful only if you want fallback mail routes or if firewall doesn't allow incoming port 25 for the server.

3.9.1. Mail gateways to forum and tracker

When forum or tracker is monitored, replying to monitor mails are processed by mail gateways. These gateways use FusionForge configuration file /etc/gforge/local.inc so that they can access database but the problem is that they run with different user than that of Apache. So if you want to use these gateways, you'll have to change access mode of local.inc.

3.10. File Release System (FRS)

Create a directory (e.g. /var/lib/gforge/download) and make it owned by the webserver user. This directory will be referenced in the FusionForge Config File /etc/gforge/local.inc as $sys_upload_dir.

# mkdir /var/lib/gforge/download
# chown -R apache-user/var/lib/gforge/download


For FHS-compliance, use /var/local/gforge/download.

3.11. Configuring GNU Mailman

GNU Mailman is used to help manage the FusionForge mailing lists. Mailman is frequently installed in /usr/lib/mailman but sometimes it can be found in /var/mailman. You should change FusionForge configuration variable $sys_path_to_mailman to that Mailman directory.

Cronjobs for Mailman are located in cronjobs/mail/*. cronjobs/mail/mailing_lists_create.php is used obviously to create new mailing lists.

For all problems with Mailman installation and use, contact the Mailman mailing lists for help.

To install it:

  1. Install a GNU Mailman package or compile it

  2. Don't integrate Mailman with Postfix (or other MTA) by delegating it generation of alias-style file. FusionForge generates such file. But you'll need to put mail aliases in /etc/aliases for the required standard mailman mailing list. Create it with:

    # /usr/lib/mailman/bin/newlist mailman
  3. Configure mm_cfg.py:

    • DEFAULT_HOST_NAME and DEFAULT_URL should point to lists.gforge.company.com. These variable names may vary depending on Mailman distribution.

    • Strip ugly cgi-bin from URLs in configuration parameters.

  4. su to root and set the Mailman password by using the mmsitepass command

  5. Create directory /var/www/mailman/. It will be document root for lists.gforge.company.com.

  6. In Web server configuraton, create virtual host for Mailman, adjusting ScriptAlias and Alias directives:

      ServerName    lists.gforge.company.com
      ServerAdmin   webmaster@gforge.company.com
    # You may want to add these files to logrotate, or just use cronolog as shown below
      CustomLog "/var/log/gforge/lists/access.log" combined
      ErrorLog  "/var/log/gforge/lists/error.log"
    #  CustomLog "|/usr/bin/cronolog /var/log/gforge/lists/%Y/%m/%d/access.log" combined
    #  ErrorLog  "|/usr/bin/cronolog /var/log/gforge/lists/%Y/%m/%d/error.log"
      DocumentRoot  /var/www/mailman
      DirectoryIndex index.html
      ScriptAlias   /mailman/ /usr/lib/cgi-bin/mailman/
      Alias         /pipermail/ /var/lib/mailman/archives/public/
      Alias         /images/ /usr/share/images/


    Check that ScriptAlias and Alias directories are correct. The example values are for Debian 3.1 (Sarge).

3.11.1. Mailing list for commits

When repositories are created, mailing list project-commits@lists.gforge.company.com is created too. Note that project administrators should manually set Privacy Options... / Sender filters / accept_these_nonmembers to something like ^.*@servername\.company\.com where servername.company.com is name of the host where Mailman is installed (lists.gforge.company.com).

3.12. Source Code Management (SCM)

CVS and Subversion (SVN) are popular SCM systems that may be installed as plugins, as shown later. You'll have to make their needed directories:

# mkdir /var/www/scmtarballs
# mkdir /var/www/scmsnapshots

These directories correspond to FusionForge configuration variables $sys_scm_tarballs_path and $sys_scm_snapshots_path.


For FHS-compliance, use /var/local/gforge/scmtarballs and /var/local/gforge/scmsnapshots.

3.13. Cron Jobs

Cron jobs are in the cronjobs/ directory and the crontab.in file contains a sample crontab. This gives you the basic cronjobs for updating certain statistics and data on the site.

cronjobs/cvs-cron/ contains scripts useful for creating blank cvs trees and managing the /etc/groups, /etc/passwd and /etc/shadow files. See cronjobs/README.root and CVS plugins section for more info.

cronjobs/mail/ contains files useful for the creation of new mailing lists in mailman and creating the /etc/aliases file.

Prepare for cronjobs/cvs-cron/usergroup.php and cronjobs/mail/mailaliases.php.

# adduser anonymous
# cp /etc/aliases /etc/aliases.org
# cp /etc/shadow /etc/shadow.org
# cp /etc/passwd /etc/passwd.org
# cp /etc/group /etc/group.org


There are two other ways to authenticate FusionForge users: LDAP and NSS with PostgreSQL backend. They are not discussed in this guide.


The cronjobs/cvs-cron/usergroup.php cron script will meddle with your /etc/passwd, /etc/group, and /etc/shadow files. By default, this cron will save these files with a .new extension. You will have to edit the cron script to remove the .new extension, but you must make sure that it is properly generating your files or your server could be unusable.


The following command will blow away any existing root crontab:

# crontab cronjobs/crontab.in

Now edit the paths to the cron scripts by setting the value of GFORGE and PHP variables:

# crontab -e

Uncomment entries for cronjobs/cvs-cron/usergroup.php, cronjobs/mail/mailing_lists_create.php, and cronjobs/mail/mailaliases.php but not before understanding the consequences.

3.14. Verifying the Installation

To verify if everything was installed correctly, use the browser and connect to FusionForge. You should see the FusionForge homepage. You will need to either disable CVS and SVN plugins in some way, or configure them before making the first test.


If you get an Error: Could Not Connect to Database, check if you have followed all installation instructions for the database. Also, you can experiment with making the settings in pg_hba.conf a bit more trusting - for example, change the last work of the second line from md5 to trust.

3.15. Creating the Admin User

Site admins are anyone who is an admin of group_id=1.

  1. Connect to FusionForge and register a new account.

  2. Insert a valid email address; this will be used for the account confirmation.

  3. Open your e-mail client, wait for the email from FusionForge site and follow the link that appears on the message.

  4. Verify in Account Maintenance the user id of the user registered.

    Usually this is 102, but you can verify this by running the following SQL query via the PostgreSQL psql utility:

    $ psql -U gforge -W -h localhost gforge
    gforge=> SELECT user_id FROM users WHERE user_name='YOUR USER NAME';
  5. Now set up the newly added user to be a FusionForge administrator:

    gforge=> INSERT INTO user_group (user_id,group_id,admin_flags)
    gforge-> VALUES (102,1,'A');

One of the first string as FusionForge administrator is to initialize once the reporting tables from Reporting tab.


Once you have set up this user as an administrator, you can use FusionForge web interface to add more administrators.

3.16. Customizing Front Page

If you want to customize front page, you'll have to provide new index_std.php:

  1. Create /etc/gforge/custom directory.

  2. Set $sys_custom_path configuration variable to /etc/gforge/custom.

  3. Copy /var/www/gforge/www/index_std.php to /etc/gforge/custom/index_std.php and edit it as you like.

3.17. Optional Features

3.17.1. Project webs

Each project can have its own virtual host projectname.projects.gforge.company.com. Location of project files is configured with $groupdir_prefix variable in FusionForge configuration file. Each project has directory with project's name and contains htdocs subdirectory where Web files are placed. Project directories are created by cronjobs/cvs-cron/usergroup.php. DNS Server Configuration (BIND)

Project virtual hosts require new DNS zone. Making this new zone is similar to making DNS zone for FusionForge itself.

  1. Declare new zone in gforge.company.com zone:

    projects        IN      NS      ns.projects.gforge.company.com

    If DNS server doesn't serve the new projects.gforge.company.com zone, add the following line too:

    ns.projects     IN      A

    Don't forget to change serial number of gforge.company.com zone!

  2. Create new zone file with following content:

    $TTL    2d
    @       IN      SOA     projects.gforge.company.com. hostmaster.gforge.company.com. (
                                  1         ; Serial
                             172800         ; Refresh
                                900         ; Update retry
                            2419200         ; Expire
                               3600 )       ; Negative Cache TTL
    @               IN      NS      ns.projects.gforge.company.com.
    @               IN      A
    ns              IN      A
    *               IN      A
  3. The new zone must be added in main BIND configuration file:

    zone "projects.gforge.company.com" {
            type master;
            file "/dist-specific/path/to/zone-file";
  4. Reload BIND and test if all works:

    $ host test.projects.gforge.company.com
    test.projects.gforge.company.com has address Web Server Configuration (Apache)

Module vhost_alias should be enabled and the following directives should be added to httpd.conf (if /var/www/homedirs/groups is what you have chosen in $groupdir_prefix):


If you want to be FHS-compliant, you may use /var/local/gforge/log and /var/local/gforge/homedirs.

# WARNING - security is degraded by having this
# on the same machine as the primary FusionForge
  ServerName        projects.gforge.company.com
  ServerAlias       *.projects.gforge.company.com
  ServerAdmin       webmaster@gforge.company.com
  UseCanonicalName  Off

# You may want to add these files to logrotate, or just use cronolog as shown below
  CustomLog "/var/log/gforge/projects/access.log" combined
  ErrorLog  "/var/log/gforge/projects/error.log"

#  CustomLog "|/usr/bin/cronolog /var/log/gforge/projects/%Y/%m/%d/access.log" combined
#  ErrorLog  "|/usr/bin/cronolog /var/log/gforge/projects/%Y/%m/%d/error.log"

  DocumentRoot        /var/www/homedirs/groups
  VirtualDocumentRoot /var/www/homedirs/groups/%1/htdocs
  <Directory /var/www/homedirs/groups>
    Options Indexes
# WARNING - turning on php will allow any user
# to upload a php file to your server, and include 
# the gforge local.inc file and get your password to 
# connect to the database and have total control.
    php_flag engine off
    AllowOverride None
    Order allow,deny
    Allow from all
  DirectoryIndex index.html index.htm


cronjobs/cvs-cron/usergroup.php copies from cronjobs/cvs-cron/default_page.php to /var/www/homedirs/groups/projectname/htdocs/index.php but the above configuration disables PHP.

3.17.2. Full Text Indexing

If you want to enable full text indexing, follow these steps:

  • Find tsearch2.sql in your distribution of PostgreSQL and run it:

    # su - postgres
    $ psql -f /path/to/tsearch2.sql gforge

    Since gforge PostgreSQL user is not superuser, access to some Tsearch2 tables should be additionally granted:

    # su - postgres
    $ psql gforge
    gforge=# GRANT SELECT ON pg_ts_dict TO gforge;
    gforge=# GRANT SELECT ON pg_ts_parser TO gforge;
    gforge=# GRANT SELECT ON pg_ts_cfg TO gforge;
    gforge=# GRANT SELECT ON pg_ts_cfgmap TO gforge;
  • Import data definitions:

    $ cd /var/www/gforge/db
    $ psql -U gforge -W -h localhost -f FTI.sql gforge
    $ psql -U gforge -W -h localhost -f FTI-20050315.sql gforge
    $ psql -U gforge -W -h localhost -f FTI-20050401.sql gforge
    $ psql -U gforge -W -h localhost -f FTI-20050530.sql gforge
  • Enable Full Text Indexing by setting $sys_use_fti in FusionForge Configuration File local.inc.

3.17.3. JPGraph

PHP must be compiled with --with-gd, or appropriate package must be installed. Extra fonts for JPGraph are not necessary. Be sure your /etc/gforge/local.inc file contains the proper path to the jpgraph/src/ directory.

Manual installation can be done like this:

# tar -xzf jpgraph-1.19.tar.gz
# mkdir /var/www/jpgraph
# cp -R jpgraph-1.19/src/* /var/www/jpgraph


If you want FHS-compliance, /usr/local/share/jpgraph

When you get your preferred version of JPGraph installed, you will have to edit one setting in jpgraph.php (or jpg-config.php, depending on JPGraph version):



Be careful with JPGraph license: versions > 1.5.2 are not free (as in free speech). You must check license before use.

3.17.4. Perl

If you want to use some of the Perl scripts that access the database, you'll need the DBI and DBD::Pg Perl modules. On Red Hat systems (and variants), you can get them by installing the libdbi and libdbd-pgsql packages. On Debian systems (and variants), the packages are called libdbi-perl and libdbd-pg-perl.

You'll also need to install utils/include.pl to /usr/share/gforge/lib/, and put some configuration variables into /etc/gforge/local.pl. In particular, you'll need something like the following in local.pl:

$sys_default_domain = 'gforge.company.com' ;
$sys_dbhost = '' ;
$sys_dbname = 'gforge' ;
$sys_dbuser = 'gforge' ;
$sys_dbpasswd = 'p455w0rd' ;

3.17.5. Jabber Support

FusionForge supports the sending of messages to jabber accounts. To accomplish this, you must have a user account setup on the jabber server that gforge can connect to and send messages.

Once you have that user account, server, and password set up, just edit /etc/gforge/local.inc and add the information to the jabber section.

3.17.6. Peer Ratings

Add yourself, and any others you wish, to the “Peer Ratings” project, which should be at /projects/peerrating/ on the website. Make yourself an admininistrator of the project, and then proceed to “rate” other users on the website.

Members of the “Peer Ratings” project, who are administrator of the project, become the first trusted users. This is the only way to prime the pump for the peer ratings system.

4. Plugins


Since FusionForge 4.0, plugins are necessary as source code management is now provided by plugins (SCM* plugins).

For each plugin, you can find an INSTALL file in the plugin tarball.

4.1. CVS

4.1.1. Overview

CVS is now managed via the scmcvs plugin which is included in the plugins/ directory in the tarball downloaded from gforge.org. Most of the files in scmcvs are intended for auto-installation on Debian systems and do not apply to the majority of users. The scmcvs plugin is activated by default in the gforge.sql database and all that you have to do is copy the plugins/scmcvs/etc/* directories to /etc/gforge directory and possibly modify the files slightly.

4.1.2. Cronjobs

Cronjobs for CVS are included in cronjobs/crontab.in, but are commented out by default for your security. The CVS cronjobs are in /var/www/gforge/cronjobs/cvs-cron and consist of:

  • usergroup.php creates user and groups in /etc/passwd, /etc/shadow, and /etc/group.

  • cvs.php creates repositories.

  • ssh_create.php copies SSH keys to user directories.

  • history_parse.php collects statistics.

There are other cronjobs that can be activated too:

  • plugins/scmcvs/cronjobs/tarballs.php creates tarballs

  • plugins/scmcvs/bin/snapshots.sh creates tarballs. CVSROOT and SCMSNAPSHOTSDIR variables are hard-coded in the script, so you'll have to edit the script if necessary.

Make sure these files are executed as root, and have proper execution bits set. Each of these cronjobs has configuration parameters which you may have to edit manually for your specific system. Here is a list of CVS cronjobs:

If you are using CVS 1.12, replace syncmail with updated version.

# cd /var/www/gforge
# cp plugins/scmcvs/bin/syncmail-cvs-1.12 cronjobs/cvs-cron/syncmail

Replace %1{sVv} in /var/www/gforge/cronjobs/cvs-cron/cvs.php with %p %{sVv}. Search for LockDir= in cronjobs/cvs-cron/cvscreate.sh and add the following line after it:

echo "UseNewInfoFmtStrings=yes" >> $repositorypath/CVSROOT/config

4.1.3. Installation


This guide doesn't cover chrooted CVS repositories which are always recommended.

  1. Create default location for CVS repositories ($cvsdir_prefix in FusionForge configuration file):

    # mkdir /cvsroot
  2. Optional: Set up basic index.php file for CVS virtual host if desired. This guide has not further instructions on enabling CVS virtual host.

    # mkdir /var/www/cvs
    # cp /var/www/gforge/cronjobs/cvs-cron/www/* /var/www/cvs
  3. Copy the scmcvs plugin config to /etc/gforge:

    # cp -R /var/www/gforge/plugins/scmcvs/etc/* /etc/gforge
  4. Make sure the cvs crons are executable:

    # cd /var/www/gforge/cronjobs/cvs-cron/
    # chmod 755 *.php *.sh
  5. Copy CVS restricted shell:

    # cp /var/www/gforge/cronjobs/cvs-cron/cvssh.pl /bin
  6. Edit FusionForge Config File /etc/gforge/local.inc and change $sys_path_to_scmweb to be /var/www/gforge/plugins/scmcvs/cgi-bin.

  7. You may have to edit /etc/gforge/plugins/scmcvs/cvsweb.conf to change the cvsroot location:

    'gforge'  => ['FusionForge-CVS', '/cvsroot/'],
  8. Install the following non-core Perl modules:

    • IPC::Run

    • URI::Escape

  9. You may want to user CVS pserver. First, assure that cvspserver service is defined in /etc/services. It will look like this:

    cvspserver      2401/tcp
    cvspserver      2401/udp

    Add entry for pserver in /etc/inetd.conf:

    cvspserver stream tcp nowait root /var/www/gforge/plugins/scmcvs/bin/cvs-pserver cvs-pserver

    Make sure that the wrapper script is executable:

    # chmod +x /var/www/gforge/plugins/scmcvs/bin/cvs-pserver

    The used wrapper script /var/www/gforge/plugins/scmcvs/bin/cvs-pserver assumes that CVS repositories are in chroot environment and you may want to edit the script and change CHROOTDIR and CVSROOT variables.


    CVS pserver has long history of vulnerabilities and its use is highly discouraged.

4.2. CVSTracker

4.2.1. Overview

The cvstracker plugin allows for some integration between CVS commits and the bug tracker and task manager. So, for example, when you commit, you can reference bug and task IDs in your commit message and have the commit linked to the corresponding bug and task.

See the plugins/cvstracker/README file for details. This plugin is enabled by default in the gforge.sql database file. As with the other plugins, you may manually place the config files in /etc/gforge/plugins/cvstracker/ and uncomment the cronjob in crontab.in.

You will also have to copy the newcommit.php file to your gforge www/plugins/cvstracker/ dir

4.2.2. Installation

# cd /var/www/gforge/plugins/cvstracker/
# cp -R etc/plugins/cvstracker/ /etc/gforge/plugins/

Edit /etc/gforge/plugins/cvstracker/config.php and change parameters.

Uncomment update_loginfo.php in crontab.


CVS Tracker is not enabled by default for project. You'll have to manually enable it.

4.3. SVN

4.3.1. Overview

SVN is also managed via plugin. The scmsvn plugin is included and activated by default in FusionForge. As with scmcvs, you have to move the scmcvs/etc/plugins/* files to /etc/gforge/plugins/* and may have to make minor modifications for your specific setup.

There are two ways to manage SVN. One is to have SVN over DAV and the other is to have SVN over SSH just as you do with CVS. If you choose to use DAV, you will need the mod_auth_gforge library compiled and installed in your apache and the appropriate virtual host settings in your httpd.conf. mod_auth_gforge is available from gforge.org. The cronjobs to manage SVN are in cronjobs/dav-svn/ and so are sample httpd.conf virtual host settings. Each of these cronjobs has configuration parameters which you may have to edit manually for your specific system.

Configuring svnserv for svn-over-ssh:

4.3.2. Installation


Instructions here are far from complete.

#Create default location for SVN repositories
mkdir /svnroot

# Optional - Set up some basic files for SVN-over-DAV only
mkdir /var/www/svn
cp /var/www/gforge/cronjobs/dav-svn/www/* /var/www/svn/

#copy the scmsvn config files to /etc/gforge/
cp -R gforge/plugins/scmsvn/etc/plugins/scmsvn/ /etc/gforge/plugins/

5. Upgrading Existing Install

You will upgrade your database from a prior version by applying each database schema change, in order, and applying it only once. Only apply the schema changes in the db/ folder that are dated after your existing installation.

There may also be migration scripts that have to be run. In the db/ folder, look for php scripts and run them.


You have to apply database schema changes and to run migration scripts in the right order.

6. Most Common Problems

Q: I get a blank page when I visit http://gforge.company.com/

A: Most often you are missing the php-pgsql library that lets PHP talk to the postgres database. Find a php-pgsql RPM or recompile php to have pgql support.

If you're sure you have php-pgsql support, you can edit common/include/database.php and remove the @ symbol from this line:

$conn = @pg_connect( 

So that it looks like:

$conn = pg_connect(

This will let debug output dump to the screen and may let you find the problem. Search the forums for more solutions.

Q: “Error Occurred In the Logger” or other database permission problems

A: As stated in the installation instructions, the database must be created, owned, and accessed by the gforge user. This user is the only one who will have total acess to all the tables. Any other user would have to be specifically granted permissions with the GRANT commands in postgres.

Q: Reporting or time tracking doesn't work

A: Go to the reporting tab and scroll down so you can choose “Initialize/Rebuild Reporting Tables

You may also be missing GD support or be missing JPGraph or have it installed improperly. The jpgraph/src/ directory should be specified accurately in your local.inc file, and you should include a / at the end of the path specified. In addition, you should modify jpgraph.php to set USE_CACHE=false.

Q: How do I upgrade my database?

A: As stated above, you must apply the changes that are listed in date order in the db/ directory to your database. Only the changes that are not already in your old db/ directory should be applied, and they should be applied and checked in order.

Q: I'm getting an error about BaseLanguage.class.php not being found.

A: Make sure your localization path is correctly specified in the local.inc file and that it is readable and writable by the apache user.

Q: When I click on “/projects/” or “/users/” links, I get the source code instead of the page I expected.

A: As shown in the example httpd.conf files above, you may have to switch to using the <Files> or <Location> directives depending on your server version.

Q: How do I backup FusionForge?

A: The only proper way to backup the gforge database is with pg_dump. Any attempt to backup the filesystem while pgsql is running will result in a useless and corrupt backup. You can backup CVS trees using tar as long as they are not actively and heavily used during the backup. Mailman and the FRS uploads dir can also be backed up with tar.

Q: Any time i enter an apostrophe in a text box, i get a parse error

A: As stated in the instructions above, you should have magic_quotes_gpc=On in your php.ini file.

Q: Large uploads into FRS or the doc manager fail.

A: Apache and the php.ini file need to have upload limits and possibly memory limits increased.

Q: When I click on /projects/ or /users/ links, I get a Page Not Found error instead of the page I expected.

A: Switch to/from the <Files projects> from/to the <Location /projects> directives in your httpd.conf. (Q&A provided by David Morsberger)

FusionForge Administration Guide

Ken McCullagh

1. Introduction

This document is intended to be a guide for administering projects on FusionForge. It is not intended to describe how to administer the FusionForge site itself. It is assumed that the reader will have also read the FusionForge User's Guide before reading this document.

2. What is FusionForge?

FusionForge was developed by the Open Source community as an environment in which to host projects in a way that the code, documentation, binaries etc. were publicly accessible to all who wished to see them, and members of the public could use the software that was developed, and contribute feedback, bugs, ideas and suggestions, and even help to develop code/modules/documentation/resources for the software.

Traditionally it was used for software projects, although there is really no reason why it cannot be used to develop hardware or silicon projects also.

Generally, everyone needs to have read access to the data associated with a project, with (some of) the developers having write access to the data. Usually there is a maintainer of the code (the project leader or the person who registered the project) and contributers who email any changes to the code that they developed - bug fixes, additional functionality - which the maintainer adds to the code in the CVS tree upon verification that it was correct/clean/maintainable/useful.

3. What can FusionForge do for me?

FusionForge can provide a centralized access point for several useful utilities and tools which could be used in a project. Some of these tools include:

  1. A version control repository (CVS or Subversion)

  2. Mailing lists

  3. Discussion forums

  4. Bug tracking

  5. A web interface to CVS or Subversion

  6. Task lists

  7. A website which provides some usage statistics, including the project members, the number of mailing lists, source code statistics, the number of items in the discussion forums, etc.

4. Setting up a new project

In order to get a project up and running, you must be registered as a user of FusionForge. This is described in the FusionForge Users Guide.

5. Registering a new project

It is quite straightforward to register a new project on FusionForge. The steps involved are:

  1. Login to FusionForge

  2. Select Register New Project from the menu on the left hand side of the page.

  3. Fill in the Full Name, Unix Name, Project Purpose and Summarization fields (paying attention to the restrictions listed on the page) and select a license type.

  4. Click Proceed with this registration and assuming that all the details are correct, and that the name is unique, the project will be accepted pending approval. If there are details missing, or other errors, you will be informed of the problem.

  5. Assuming that the project is approved, you will be sent back an email confirming that this is the case, and listing the website, cvsroot etc of the project you created. It will take some time for the cvsroot to be created - usually by an overnight cronjob.

Once you have received the email confirming project acceptance, you will be able to find your project through the search box by enteringyour project's name or details. Clicking on the link provided will bring you to the project summary page which is the default starting point for all the project administration.

6. Administering a new project

This section provides an oversight on how to set up the FusionForge utilities so that they can be used by your project once it has been approved. Typically the cvs space will have been allocated by the morning after the confirmation email is sent to the project requester. In order to get the project into a useable state, the project administrator will need to perform some steps.

7. CVS repository

If the project does not already have a CVS repository in place (eg if an existing project is being added to FusionForge mid-life, rather than a brand new project being started) the CVS repository will need to be set up. There are plenty of resources on CVS around so this document will not attempt to describe how to use CVS, but will provide just enough information to get started.

8. Setting up the CVSROOT

Before any CVS operations can be carried out, the CVSROOT environment variable must be set in the command shell you are using, or in whatever CVS GUI you are using, such as WinCVS.

9. Setting your .rhosts file correctly

In your UNIX home directory there exists a file called .rhosts. This file requires special permissions, namely :

-rw-r--r--   .rhosts

If this is not correct, you will encounter problems trying to access CVS. If this file is not present, it must be created.

Secondly, your .rhosts file must contain the name of the machine(s) from which you are accessing CVS. The format of the file is as follows:

 machine1 username
 machine2 username

It is recommended that fully qualified domain names are used, or IP addresses, as this seems to solve problems arising due to machines in different offices accessing each other. The last line of the file may optionally be

 + username 

to allow UNIX (not Linux) machines to use wildcard matching to allow access from all hosts on the network. This does NOT work on Linux, which is what the FusionForge server runs. Also, if the wildcard entry is before the machine you wish to use, then it will not work either.

10. Creating the CVS repository

Once CVSROOT has been set, the base entry for CVS can be added. This is the top level for the directory structure of the repository.

This is done using the cvs import command. The following steps show how it can be done.

 $ cd <top of tree>
 $ cvs import <module-name> <vendor-tag> <release-tag>

e.g. suppose we wish to import a directory structure called myproject, which was obtained from "customer" and is labelled "releaseone" we would do:

 $ cd path/to/myproject
 $ cvs import myproject customer releaseone

If we wanted to create a clean, new directory structure called mynewproject we could do something like this.

 $ mkdir mynewproject
 $ cd mynewproject
 $ cvs import mynewproject mycompany start

This is pretty much all that has to be done to start up the CVS repository - after this the repository can be used in the normal way. It is also possible to import several modules to the same CVS repository. e.g.

 $ cd path/to/src
 $ cvs import src S3 src0
 $ cd path/to/docs
 $ cvs import docs S3 docs0

But as was said earlier, this is not the place to provide a complete introduction to CVS. Go out and find some of the abundant documentation that is available for it on the web and elsewhere. Most importantly, if you run into a problem with CVS, it is NOT the FusionForge administrator's fault so don't go running to them every time. Try to figure it out yourself or go looking for help on CVS related news groups.

FusionForge User Guide

Alain Peyrat


Ken McCullagh

Guillaume Smet

Reinhard Spisser

1. Introduction

This manual explains how to use the FusionForge software.

The manual is divided in 4 parts:

1.1. Getting Started

This section explains how to register as a new user, how to register a new project, how to login and how to logout.

1.2. User specific functions

This section describes the functions of FusionForge that are relative to the user's section.

This document describes the user's homepage, how to modify user settings, how to handle user ratings, skill profiles and Diary and Notes.

1.3. Project specific functions

This chapter explains the project specific functions of FusionForge.

Project Summary

This section describes the Project Summary page for your project.

Project Administration

This section describes the Administration of the project. The Project Administrator function is accessible only to the Project Administrators.


This section describes the use and administration of the Discussion Forums.


This section describes how to use the Tracker to track bugs, patches, support requests.

Mailing Lists

This section describes the creation or maintenance of mailing lists for your project.

Task Manager

This section describes how to use the Task Manager to track activities.

Document Manager

This section describes the Document Manager.


This section describes how to set up Surveys for your project.


This section describes how to add and release News for your project.


This section describes how to manage CVS repositories for your project.

File releases

This section describes how to publish new releases of your project.

1.4. Site-wide functions

Trove Map

This section describes the Project Classification System.

Snippet Library

This document describes how to use the code fragment Library.

Project Help

This document describes how to use the Project help function of FusionForge.

2. Getting Started

2.1. FusionForge homepage

Connect with your browser to FusionForge. This can be either http://gforge.org or a locally-installed version of the software.

2.2. Registering as a new user

To register a new user, click on the New Account link on the top right side of the browser window.

To register as a user, you need to fill out the form with the following data:

Login Name

You should select an unique user name to access to the system. The name should not contain uppercase letters and usually is a combination of your name and your surname; e.g. jdoe for John Doe. Also, the user name cannot match that of an existing system user account - i.e., you can't have a FusionForge user named 'root'.


You should insert your password here. It must be at least 6 characters long. You shouldn't use too obvious names for the password. It should be easy to remember for you, but hard to guess for others. So don't use the name of your dog, of your cat, or the name of your birth city.

You should use instead a combination of letters and numbers.

Full/Real Name

Here you should insert your full name.

Language Choice

Select here your preferred language. This choice does not influence only the language in which FusionForge will speak to you, but also some local specific data display, like dates, etc.


Select your timezone. Note that GMT is preselected. All dates will be showed relative to your timezone.

Email Address

You should insert your email address here.

The email address should be correct, FusionForge will send you a confirmation email for your subscription. If the email address you're inserting here is wrong, you'll never receive the confirmation email and the account you're registering will never be activated.

When you receive the confirmation email, you must connect to FusionForge using the provided URL in the email. This is the only way to become a registered user.

Receive Email about Site Updates

If you check this, you'll periodically receive information about the FusionForge site. The traffic is very low, it is recommended that you activate this option.

Receive additional community mailings

If you check this, you will receive information about the site's community.

2.3. Registering a new project

To register a new project, connect to FusionForge, login and go to My Page section. You have a Register Project link in the menu at the top of the page.

You need to insert the following information to register a project:

Project Full Name

The Name of the Project: eg. FusionForge Master project

Project Purpose and Summarization

A brief summary of the Project


You must select a License for your software.

Project Public Description

Insert a description of the Project. This description will appear in the Project Summary page

Project Unix Name

Insert here the Unix name of your project. This name must respect the following rules:

  1. it cannot match the Unix name of any other project

  2. its length must be between 3 and 15 characters

  3. only lowercase letters, numbers and dashes are accepted

The Unix name will be used for your website, the CVS Repository and the shell access for FusionForge.


The Unix name will never change. Once a project is set up with its Unix name, the name cannot be changed.

Click on the I agree button to register the project. Your project is now registered on FusionForge; but you cannot yet access it. It has to be approved from the site administrators.

When the project is approved, you'll receive an email from FusionForge confirming that the project is active.

2.4. Login

You can login by clicking the Login link in the top-right border of the browser window.

The form requires that you insert your username and your password to access the site. If the data is correct, the user homepage will be displayed.

2.5. Logout

To log out from FusionForge, click on the Logout link on the top right of your browser window.

3. User specific functions

3.1. User Homepage

The User home page appears after the user has performed the login or when he clicks the My Page tab.

The User Homepage contains a 4 links and 5 tabs.

The four links are the following:

  • My Personal Page

  • Diary & Notes

  • Account Maintenance

  • Register Project

The five tabs contain the following information:

Assigned Artifacts

This list shows the Tracker items assigned to you. Only items in the open state will be listed here. Clicking on the number of the item, you'll go to the detail of the item. The items are ordered by priority.

Assigned Tasks

This list shows the Tasks items assigned to you. Only tasks in the open state will be listed here. Clicking on the task name, you'll go to the detail of the task. The tasks are ordered by subproject.

Submitted Artifacts

This list shows the Tracker items submitted by you. Only items in the open state will be listed here. Clicking on the number of the item, you'll go to the detail of the item. The Tracker items are ordered by tracker.

Monitored Items

This list shows the Items you are monitoring. It shows the Tackers that are monitored globally, the News, the Forums and the FileModules you are monitoring. See the sections about Forums and FileModules for more details on how monitoring works.


This list shows you the active projects you are participating. When you click on a project, you will go to the project summary.

3.2. Modifying User settings

When you click on Account Maintenance on your user homepage, you get a page where you can change some data you inserted. You can change every data you inserted when you registered as user except:

  • Registration date (Member since)

  • User Id

  • Login name

3.3. Changing the language on FusionForge

You have two possibilities:

  1. If you want to change the language for your account, then go to My Page -> Account Maintenance and then, select <your language> as language. And submit.

  2. If you want your language for accessing FusionForge (even without being logged), then it's defined in the configuration of your browser. You should see a preferred list of language somewhere.

3.4. User ratings

You can be rated by other users and you can rate other users. Every time you go to the detail of a user, you can rate the user.

Ratings can be given for:

  • Teamwork/Attitude

  • Coding

  • Design/Architecture

  • Follow-Trough/Reliability

  • Leadership/Management

3.5. Skills profile

In this section you can add your skills. You can set your skills profile to public, so everyone can see it, or to private, so that only you can view it.

The information that you can insert is:

  • Language

  • Level of experience (Beginner, Master, Expert)

  • Duration of experience (6 months, 1 year, 5 years)

3.6. Diary and Notes

The Diary and Notes section allows you to simulate a basic agenda. You can insert a subject and a description of the item and select if the item is public or private.

If the item is public, every user of FusionForge can view and monitor this item.

4. Project functions

4.1. Project Summary

The project summary shows summarized information about the current project. The following information is displayed:

Project description and statistics

Description of the project and some statistics about it

Project administrators and members

List of the developers involved in the project

Latest file releases

Latest file releases published via the FRS.

Public areas

For each Tool of FusionForge, Summary Information is displayed; e.g. Public Forums (7 message in 2 forums), Bugs (4 open, 12 total).


Latest news of the project.

4.2. Project Activity

The project activity displays information about the current project activity.

You have to select an activity, a start date and an end date. Then click the Submit button.

The list of corresponding activities will be displayed.

4.3. Project Administration

The Project Administration section allows you to administer the project.

4.3.1. The Project Admin Page

The Project Admin web page is where all the administration of the project is done from. To get there, log into FusionForge, and select the project from your personal page. This will bring you to the Project Summary page.

The Project admin page is available by clicking on the Admin tab.

Clicking here will present you with links to Admin, User Permissions, Edit Public Info, Project History, VHOSTS, Post Jobs, Edit Jobs, Edit MultiMedia Data, Database Admin and Stats. The Project Admin page is only accessible to members of the project who have been granted administrator privileges. By default, the person who registers the project is given admin privileges. Other members can be granted admin rights by the project administrator(s).

4.3.2. Admin

The Admin page presents the user with Misc. Project Information, Trove Categorization, Tool Admin and Group Members.

Misc Project Information

This shows the Short Description of the project and the location of the project homepage. There's also a link to Download Your Nightly CVS Tree Tarball, but this doesn't currently work.

Trove Categorization

In order for people to be able to find the project, it must be classified in the Trove Map. This is basically a set of categories in which like projects are grouped.

Clicking on Edit Trove Categorization presets a page which allows you to select the category(s) to which the project belongs (select as many as needed).

Clicking Submit All Category Changes will set the categorizations, and you will be returned to the Project Admin page. You can change the trove categorizations during the lifetime of the project by following the above steps, as the project moves through its life.

Tool Admin

This section shows the links to the tools describes the tools listed under the Tool Admin section on the Project Admin page.

Group Members

This displays the names of the members in the project, and allows you to add members or delete them. To add members simply enter their login into the box provided and press Add User. To remove them, click on the rubbish bin to the left of their name.

Edit Roles

This allows the project admin to edit existing roles in the project and create new ones.

4.3.3. Edit Public Info

This page enables the project admin to select the information that is visible to the public and to the members of the project. It is possible to select the utilities that are used by the project, so that any that are not desired are not presented on the web page. Specifically it is possible to disable/enable:

  • Mailing Lists

  • Surveys

  • Forums

  • Project/Task Manager

  • CVS or Subversion (SCM tool)

  • pserver (CVS server with password authentication)

  • Anonymous access to CVS

  • News

  • Document Manager

  • FTP

  • Tracker

  • File Release System (FRS)

  • Statistics

It is also possible to change the home page (eg, it is possible to set up a web page on another machine, which has other information). In this case, the summary page will remain on FusionForge, pointing to the project, and the Home Page link will point to the pages specified in the Homepage Link field.

You can also change the descriptive group name and the short description. If desired you can add an email address to which all Bugs, Patches, Support Requests and Task Assignments will be sent. This could be a Mailing list or just an email address.

4.3.4. Project History

This page presents a history of the project, so you can see when major changes took place, eg members added/removed, Trove categories changed etc. There is nothing that you can do here.

4.3.5. VHosts

This section allows you to handle the different virtual hosts needed for your project. A small interface is presented where you can add, modify or delete virtualhosts.


These virtualhosts are not created immediately, they are created by a backend script (be sure that the backend script is configured in your crontab).

4.3.6. Post Jobs

This allows you to post jobs for your project, so that when non-project members visit the site, they can offer to help with the development.

4.3.7. Edit Jobs

This allows you to edit the jobs that have been posted for your project.

4.3.8. Edit Multimedia data

This allows you to publish screenshots of your project.

4.3.9. Database Admin

This allows you to maintain projects' databases.

4.3.10. Stats

This section shows you information about your project activity.

You can select:

  • Areas: tracker, forums, docs, tasks, downloads, page views;

  • Type: daily, weekly, monthly;

  • Start;

  • End.

4.4. Forums

Every project can have its own discussion forums. When a new project is created, 3 forums are automatically created:

Open Discussion

A place where to discuss about everything.


A forum where to ask for help.


A place where developers discuss about developments.

4.4.1. Creating a new forum

New forums can be created using the Admin section of the forum. When a new forum is created, you must insert a name of the forum, the description of the forum, select if the forum is public or private and if anonymous posts are allowed on the forum.

Private forums are visible only to project members. If Anonymous posts are enabled, everybody can post messages to the forum, even users that are not logged in.

You can also insert an email address where all posts will be sent.

4.4.2. Using the forum

When you click on the name of the forum, you go to the detail of the forum. Selecting visualization mode

You can select the following types of visualization for the forum lists:


Shows the messages ordered by thread. All data of the message, including the posted message itself will be visualized.


Similar to Nested, the messages will be showed in chronological order.


Shows only title, author and date of each message. Shows the messages in threaded order. Clicking on the title of the message the entire message will be displayed.


Shows only the “topic started” messages. Topic starters are the messages that starts a new thread.

You can select the number of messages for every page: 25, 50, 75 or 100. Writing a message


You can use the plain text editor or the enhanced editor to compose your messages. The enhanced editor is available if the WYSIWYG HTML editor plugin was enabled by project administrators.

You can start a new thread by clicking on Start New Thread link.

You can write a message in an existing thread by clicking on the Reply link of an existing message.

In both cases, the enhanced editor is available to compose the message. Use the tool bar to format your message.

You can modify an existing message by clicking on the Edit icon. Adding a file to a message

You can add a file to an existing message by clicking on the Add icon. Only one file can be attached to a given message. If you add another file, the first one will be deleted.

The file must not be an executable file (.exe) and must not exceed a certain size.

4.4.3. Available options

The forums have 2 very powerful options:

Save place

This function registers the number of messages already inserted in the forum and will highlight new messages the next time you return to the forum.

Monitor forum

You can select to monitor the forum by clicking on the Monitor Forum button.

If this option is enabled, every post to the forum will be sent to you by email. This allows you to be informed about new messages without being logged on to FusionForge. The name of the monitored forum will appear in the users homepage in the section Monitored Forums.

4.4.4. Forum admin

Clicking on the Forum Admin link presents you with links to Add Forum and Manage Pending Messages.

Under these links, you have a list of the forums, with for each forum a link Monitoring Users. Clicking on this link will give the list of users that monitor this forum. Add Forum

This allows you to add a new discussion forum. You can select if it is public or private (only members of the project can see it). Manage Pending Messages

This allows you to accept or reject messages posted to a moderated forum. Delete Message

To delete a message (and any followups) from a forum, just display the message and click on the Saint Andrew cross. A confirmation is required. Adjust Forum Features

To adjust forum features, click on the forum name in the forum list. This allows you to alter the properties of the forum such as the name and description, whether or not anonymous posts are allowed, if it's public and you can enter an address to which all messages are posted. Configure Forum Moderation Level

To configure forum moderation level, click on the forum name in the forum list. This allows you to select the moderation level between the following values:

  • No Moderation.

  • Moderated Level 1: To moderate anonymous posts (if allowed in public forum) and posts from non-member users.

  • Moderated Level 2: To moderate all posts (except admin posts).

4.4.5. Searching

When using a forum, a voice Forum will appear in the search combo box. Selecting Forum and inserting a text in the search box allows you to search through the text data of the forum.

4.5. Tracker

4.5.1. What is the Tracker?

The Tracker is a generic system where you can store items like bugs, feature requests, patch submissions, etc.

You can use this system to track virtually any kind of data, with each tracker having separate user, group, category, and permission lists. You can also easily move items between trackers when needed.

Trackers are referred to as “Artifact Types” and individual pieces of data are “Artifacts”. “Bugs” might be an Artifact Type, while a bug report would be an Artifact. You can create as many Artifact Types as you want, but remember you need to set up categories, groups, and permission for each type, which can get time-consuming.

When a project is created, FusionForge creates automatically 4 trackers:


Used for Bug tracking

Support Requests

Users can insert here support requests and receive support


Developers can upload here patches to the software

Feature Requests

Requests for enhancements of the software should be posted here

4.5.2. Using a Tracker

The following descriptions can be applied to any of the trackers. The functionalities between the different trackers are the same, we'll use the Bugs Tracker as example to describe the functionality of all trackers.

The Tracker provides the following functions:

  1. Submitting a new item

  2. Browsing of Items

  3. Downloading CSV file

  4. Reporting

  5. Monitoring

  6. Administration

4.5.3. Submitting a new Bug

To submit a new bug, click on the Submit New link. A form will be displayed, where you can insert/select the following data:

Assigned To

You can assign the item to a user. Only users which are “Technicians” are listed here.


You can select the Priority of the item. In the Browse list, and the homepage of the users, priorities are displayed in different colors, and can be ordered by priority.


Give a short description of the bug, e.g. Logout function gives an SQL Error

Detailed Description

Insert the most detailed description possible.

File upload

You can also upload files as attachment to the bug. This can be used to attach a screenshot with the error and the log file of the application.

To upload files, select files using the Browse button. You can upload up to 5 files at a time.


Attachments to tracker items can be no larger than 256KB.


Some custom fields may have been added by administrators. Default bug trackers propose the following additional fields: Resolution, Severity, Version, Component, Operating System, Product, Hardware, URL.

When the user is not logged, he will still be proposed to submit new bugs. If the Tracker allows anonymous posting, he will be able to post without logging in. If the Tracker does not allow anonymous posting, clicking on the Submit New link will prompt the user with the login banner.

4.5.4. Browse Bugs

The Browse page shows the list of bugs. You can create and save queries allowing filtering on any defined fields.

You can sort the items by ID, Summary, Open Date, Submitter and the Ordering (ascending, descending).

The different colors indicate the different priorities of the bug; a * near the open date indicates that the request is more than 30 days old. The overdue time (default 30 days) is configurable for each tracker.

When you click on the summary, you go to the detail/modify Bug page.

4.5.5. Modify Bugs

In the modify Bug page, you can modify the data you inserted, and also add the following information:

Data Type

This combo box lists the trackers of the project. If you select a different tracker and submit the changes, the item will be reassigned to the selected tracker.


The status indicates the status of the item. When an item is inserted, it is created in the “Open” state. When you fix a bug, you should change the state to “Closed”.

Canned Responses

Canned responses are prefixed responses. You can create canned responses for your project in the admin section and select the responses in the combo box.

The Changelog on the bottom of the page shows in chronological order the changes applied to the item. Also all followups can be viewed.

4.5.6. Monitor Bugs

You can choose to monitor a tracker as a whole, or only individual tracker entries. Monitoring an entire tracker

Go to the tracker page and select Monitor link.

To stop monitoring the tracker, select Stop Monitor link. Monitoring tracker entries

If you select the Monitor button on the top left of the Bug detail page, bug monitoring will be enabled.

When you are monitoring a bug, every change to the bug will be sent to you by email.

To disable bug monitoring, simply select the Stop Monitoring button.

4.5.7. Admin Tracker

If you are an Administrator of the tracker, you can add or change bug groups, categories, canned responses:

Manage Custom Fields

You can add new fields or change the name of ones.

You can select the type of box (select box, check box, radio button, text field, multi-select box and status) and the possible values.

Add Update Canned Responses

Canned responses are predefined responses. Creating useful generic messages can save you a lot of time when handling common requests.

Update preferences

Here you can update the following information on the tracker:


The name of the Tracker. This is the name displayed in the tracker list, e.g. Bug Submissions.


The description of the Tracker. E.g. This is the tracker dedicated to the Bugs of the project

Publicly Available

By default, this checkbox is not enabled.

Allow non-logged-in postings

If this checkbox is enabled, also non logged-in users can post items to the tracker. If this checkbox is not enabled, only logged in users can post items.

By default, this checkbox is not enabled.

Send email on new submission to address

All new items will be sent to the address inserted in the text box.

Send email on all changes

If this checkbox is enabled, all changes on the items will be sent out via email. It is useful to check this radiobutton only if in the Send email address is inserted an email address.

Days still considered overdue

Days till pending tracker items time out

Free form text for the Submit new item page

This allows you to put a specific introduction on the submit new item page.

Free form text for the Browse items page

This allows you to put a specific introduction on the Browse items page.

4.5.8. Mass Update

If you are an Administrator of the tracker, you are also enabled for the Mass Update function.

This function is visible in the browse bug page and allows you to update the following information:

  1. Priority

  2. Assignee

  3. Status

  4. Canned Response

When this function is enabled, a checkbox will appear at the left side of each bug id. You can check one or more of the ids, select one or more of the values in the Mass Update combo boxes and click Mass Update.

All selected bugs will be modified with these new value(s). This function is very useful if you need to change the same information for more bugs; e.g. assigning 5 bugs to one developer or closing 10 bugs.

This function allow to update all selected box fields, not only mandatory fields but also custom fields.

4.5.9. Reporting

The reporting functions allows to check the life-span of the Bug. The lifespan is the duration of the bug; it starts when the bug is inserted (opened) in the tracker and ends when the bug is closed.

  • By assignee

  • Response time

4.5.10. Searching for bugs

When using a tracker, a voice with the name of the tracker will appear in the search combo box. The search will be done on the description, the summary, the username of the submitter and the username of the assignee.

Giving a number will redirect to the corresponding tracker id.

4.5.11. Adding a comment to a tracker by e-mail

When a user receives an e-mail about a tracker, he can add add a comment to this tracker by replying to this e-mail.


The e-mail reply must use plain text format. An HTML e-mail will lead to an error message.

4.5.12. Managing trackers via CLI (Command-Line Interface)

We give here some basic examples of CLI commands. For more information, please consult the FusionForge Command-line interface (CLI) documentation. Logging in with CLI
gforge.php -v login --username="user" --project=myproject Getting the list of tracker entries via CLI

Use CLI to get the tracker id for a given project

gforge.php tracker typelist

Use CLI to get the list all bugs for a given project

gforge.php tracker list --type=xxx Creating a tracker entry via CLI
gforge.php tracker add --type=xxx --priority=4 --summary="New bug" 
                       --details="This is a brand new bug" Updating a tracker entry via CLI
gforge.php tracker update --type=xxx --id=yyyy --priority=5 
                   --summary="New summary" --details="New details"

You can include a Custom Field, e.g. Group

gforge.php tracker update --type=xxx --id=yyyy --priority=5 
                          --summary="New summary" --group=zzzz

4.6. Mailing Lists

This is where you will set up and administer the mailing lists associated with the project.

4.6.1. Main page

This page shows the list of available mailing lists.

Clicking on List Name Archives will allow you to browse the archives of the selected mailing list.

You can subscribe, unsubscribe or edit your preferences for a specific mailing list by clicking the appropriate link.

There is a special mailing list named '<project>-commits' which is populated by all the commits performed in CVS or Subversion. By simply registering to this mailing list, any user can be informed of the SCM activity on the project.

4.6.2. Admin

This brings you to the Mail Admin page, where the following options are available to you.

Add Mailing List

Clicking here will allow you to create a new mailing list. You can specify if it is to be made public (people who are not members of the project can see and/or join it) or not. You can also add a description of the list. You will receive an email with the administration password of the list.

Administrate/Update Lists

This allows you to change the description of the list, the state of the list, and by clicking on Administrate this list in GNU Mailman you can add members to the mailing list, set the properties of the list, posting policies and so forth.

Delete a Mailing List

This allows you to permanently delete a mailing list.

Select the Update link of the list. Then click on the Permanently Delete List link.

4.7. Task Manager

The Task Manager is similar to the tracker, with the following differences:

  • you can insert the start date of the item

  • you can insert the end date of the item

  • you can insert the number of hours for the item

  • you can have multiple assignees for the item

  • you can handle dependencies between tasks

Tasks are organized in subprojects. Before inserting a new task, you must first create a subproject. You can use the Admin link to create new subprojects.

Tasks allows you to create and manage tasks, or blocks of work, similar to the way projects are broken down in e.g. Microsoft Project.

4.7.1. Inserting a new Task

This allows you to add tasks to the sub projects - e.g. Write Design Doc, Review Doc, Update Doc, Write Code, Review Code, Update Code, Test, Log Test Results, etc. They can be assigned to members of the team, and start and end dates set up for them, dependencies on other tasks set, percentage completion etc.

You need to select first a subproject from the subproject list and then select the Add Task link.

A form appears, where you are requested to insert the following data:

Percent Complete

You can select here the Percentage of the completion of the work.


You can select here the priority of the task.

Task Summary

You should insert a brief description of the task.

Task Details

You should insert here the most detailed description possible of the task.

Start Date

You can insert here the start date.

End Date

You can insert here the end date of the task.

Assigned To

You can select one or more assignees of the task. Only users which are defined as “Technicians” are listed here.

Dependent on task

You can select here one ore more task upon which this task depends.


It is the estimated duration of this task in hours.

Only Administrators can add new items on the Task Manager; only Administrators can make changes to the task; only administrators can close the task.

4.7.2. My Tasks

It lists the tasks assigned to the user.

4.7.3. Browse Open Tasks

It lists all tasks in the open state.

4.7.4. Reporting

The Reporting is similar to the reporting section of the Tracker.

4.7.5. Task Admin

The Admin section allows you to:

Add a project

You can select if the subproject is public (visible to everyone) or not (visible only to project members).

This allows you to add a subproject to a project, such as modules, documentation, etc.

Required arguments are Project Name and description.

Update information

Here you can select if the project is public, private or deleted (visible to nobody) and update the name and description of the subproject.

Register an e-mail address for notification of tasks

Fill the 'Send All Updates To:' box with an e-mail address.

4.8. Document Manager

The Document Manager provided with FusionForge gives you a simple way to publish documents on the site.

4.8.1. Submit new documentation

Here you can submit new documents for approving/publishing on the site. The form requires you to insert the following information:

Document Title

The document title refers to the relatively brief title of the document


A brief description to be placed just under the title.

Upload File

Here you should select the file to be uploaded. You can upload text files (.html, .txt) or binary files (.zip, .doc, .pdf).

Reference File (by an URL)

Instead of uploading a file, you can specify the URL where the document is located.


You should select here the language of the document.

Group that document belongs in

You should select here the group of the document. This feature is used to categorize documents.

Fill in all the fields, select the group from the drop down list and click Submit Information. The document will then be placed in the Pending Submissions section of the DocManager Admin page, to be approved or rejected.

4.8.2. Viewing existing docs

The View Documentation page shows you a list of documents published and approved for viewing; grouped by Document groups. You can click on a document to view the entire content.

4.8.3. Admin

Clicking on this will present you with a page showing pending and active documents. In order to allow users to submit a document, you must first set up the document groups for the project.

The Admin section allows you to:

Approve/publish pending submissions

The Pending Submissions list shows the list of submissions that are waiting for your approval. Clicking on the document name, the Edit Document form will be displayed.

Edit Documents

The Edit Document links shows all states of the documents, and the documents in the state:

Active Documents

Active Documents are displayed in the View Documentation list.

Pending Documents

Pending Documents are waiting for your approval.

Hidden Documents

Hidden documents are not displayed.

Deleted Documents

Deleted Documents are old, outdated documents.

Private Documents

Private documents are displayed only for members of the project.

Edit Document Groups

Clicking on this will present you with a box and a button to add document groups, and it also shows the document groups associated with this project. Submit as many document categories as you wish - eg Howto, Release notes, FAQ, etc. These groups will be the categories the documents will fall into when users submit documents.

4.8.4. Edit Document

When you select a document from one of the lists, a form will be displayed. In this form you can change the Document Title, the Short Description, the Language, the Document Group and the State.

If the Document is a text file with .txt, .html or .htm extension, a textbox appears where you can edit the content of the document.

If the Document is a binary document, you can upload a new version of the document.

4.9. Surveys

4.9.1. Introduction

Surveys allow you to ask questions to your developer/users and view the results. Surveys are often very helpful if you need some feedback from the users, examples of surveys might be:

  1. User feedback: ask users if they like your project

  2. Developer feedback: ask developers on new features to be implemented

Of course, surveys are not limited to this list. Basically, you can ask everything you want with surveys.

4.9.2. Administering survey questions

Before you can add/modify existing surveys, you need to administer the questions for your surveys. Questions are global for all surveys.

FusionForge surveys handle the following question types:

  1. Radio Buttons 1-5: This type of question shows 5 radio buttons where the user can select between 1 (low) and 5 (high).

    This is useful for indicating priorities or quality feedback (e.g.: the question might be: did you like the new xxx feature. The user can select (1 (not very much), 2,3,4, 5(really)

  2. Radio Buttons Yes/No. This type of question allows only two choices: Yes or No.

  3. Comment Only

  4. Text field: This type of question allows the user to insert some text in a text field.

  5. Text area: This type of question allows the user to insert some text in a textarea

When inserting new questions or modifying existing questions, take note of the ID of the question. You'll need them when creating/modifying surveys.

4.9.3. Creating a new survey

You can create a new survey by clicking on the Admin link and then Add a new survey.

You'll be asked to insert the following data:

Survey name

The name of the survey

Question list

Here you should insert the IDs of the questions in the order they should appear. If you wish to see question 4 first, then question 6, then question 1, you should insert here 4,6,1.


Don't insert spaces or any character other than comma between the numbers.

Is Active?

This flag indicates if the survey is active or not.

4.9.4. Modifying a survey

You can modify an existing survey, although this is not recommended if answers to the survey have already been given.

You should know that the results of a survey are not consistent if you modify the survey and users have already inserted answers.

4.9.5. Viewing survey results

If you have admin rights, you can view the results of the surveys clicking on the View Results tab.

You can export the survey results in a file in CSV format. This file can then be imported in a spreadsheet like Open Office Calc or Microsoft Excel.

4.10. News

The news section allows you to insert news relative to your project. A news can be monitored similar to tracker items, forums. News will be displayed on the project homepage and also on the site homepage, if the site administrators approve the news.

News are generally used to announce software releases, milestones, or significant changes in the software.

4.10.1. Inserting a news item

You can insert a news item by clicking on the Submit link.

You can post news about your project if you are an admin on your project.

All posts for your project will appear instantly on your project summary page. Posts that are of special interest to the community will have to be approved by a member of the administration team before they will appear on the FusionForge home page.

You may include URLs in your submissions. URLs that start with http:// are made clickable.

HTML is allowed in your submissions but filtered.

The news item will go to the News Admin for approval for publication.

4.10.2. Modifying/Approving a news item

You can modify or/and approve a news by clicking on the Admin link.

You can select the status of the news: Displayed or Deleted (the news will be deleted), you can insert the Subject (title) and the details.

4.10.3. Subscribing RSS feed for project news

You can subscribe a RSS feed for project news by clicking on the RSS icon on the Summary page of the project.

4.11. CVS

The CVS button shows a page that contains information on how to access the CVS repository. Use this information to configure your client for CVS access.

This page also displays some statistics about the selected project's CVS tree.

The Browse CVS Repository link opens the viewcvs web interface, where you can view the CVS repository, view differences between revisions, download versions of a file.


Only public projects will show the browse CVS repository link.

4.12. File Releases

4.12.1. Introduction

The File Releases System (FRS) is used to upload files to the FusionForge site and to make these files available to the users in an easy and efficient way.

Files can be divided in different packages, and every single package can be monitored by the users; these users will receive an email every time a new file has been added to the package.

4.12.2. Administration

The FRS system allows you to upload file to FusionForge and make this file available to the public.

You have to define a package before you can release a file. A package should have a descriptive name for the project, e.g. gforge3.

To add a new package, insert a package name in the textbox at the bottom of the page and click Create this Package.

You can use the radio buttons to make the package publicly viewable or not. Default is public.

You can use the menu buttons to make the package active or hidden. Hidden packages will not be listed in the Files section.

Your package will appear in the Releases list at the bottom of the page.

Click Add release. The form has the following fields:

Package ID

You can select here the package.

Release Name

Insert here the name of your release. The name should be indicative for the version of your file, e.g. pre-8.

Release Date

The Release Date.

File Name

Click the Browse button to select the file to upload. In some browsers you must select the file in the file-upload dialog and click OK. Double-clicking doesn't register the file.


You can't upload file that exceed the UploadFile Limit in php.ini.

File Type

You can select here the file type (.zip, .html, .exe, .tar.gz, etc).

Processor Type

You can select here the processor required to run the application.

Release Notes

The release notes.


The changelog.

Click the Release File button. Your file will now appear in the list of files in the File section.

4.12.3. Managing packages and releases via CLI (Command-Line Interface)

We give here some basic examples of CLI commands. For more information, please consult the FusionForge Command-line interface (CLI) documentation. Logging in with CLI
gforge.php -v login --username="user" --project=myproject Getting a list of releases

Get the package id

gforge.php frs packages

Get the list of releases of a given package

gforge.php frs releases --package=xxx Add a release of a given package
gforge.php frs addrelease --package=xxx --name="My new release" Edit a release

Add a text file to a release of a given package.

gforge.php frs addfile --package=xxx --release=yyy --file=zzz

Retrieve file on the standard output

gforge.php frs getfile --package=xxx --release=yyy -id=www

Retrieve file in a file

gforge.php frs getfile --package=xxx --release=yyy -id=www 

4.12.4. Monitoring packages

You can monitor a package by clicking on the envelope next to the package name. The envelope now bears a red symbol.

You can unmonitor the package by clicking again on the envelope.

4.12.5. Subscribing RSS feed for a package

You can subscribe a RSS feed for a package on the summary page of the project, by clicking on the RSS icon and select Developer New Project Releases.

5. Site-wide functions

5.1. Introduction

The side-wide functions are available anytime, they are not dependent on the single projects.

The site-wide functions handle data that are not relevant to a single project, as code fragments, project classification, project helps, etc.

The single site-wide functions available to the users are:

  • Project help

  • Search

  • Snippet Library

  • Trove map

5.2. Searching in FusionForge

You can search in FusionForge for the following arguments:


You can search for login name or the complete username. The search is not case sensitive. Inserted text must be at least 3 characters.


You can search for software groups. Inserted text must be at least 3 characters.


You can search for skills inserted by the users. Only public skills profiles can be searched. Inserted text must be at least 3 characters.

You can search for People or Software groups by selecting the item in the combo box and inserting the search text in the text box.

If the user is inside a project, he can search on all the items of the project (trackers, forums, mailing lists, tasks, releases, documents, news and wiki); he can also search on a specific item by selecting the corresponding search.

An advanced search is also provided to precise the search on a project.

5.3. Trove map

This allows users to classify their projects in a tree so that they can be found more easily.

5.4. Snippet Library

The Snippet Library function of FusionForge is very interesting; it allows to collect all the type of information/knowledge which is not a complete piece of code and which is usually difficult to organize/share.

A typical example are sophisticated shell commands, javascript functions, perl one-liner, SQL expressions that perform special queries, an algorithm, etc.

5.4.1. Inserting a new snippet

You can insert a new Snippet by clicking on the Submit a New Snippet link.

A form appears, where the following information can be inserted:


Insert the title of the snippet. This will be displayed in the list of the snippets.


Insert the description of the snippet.


Select the type of the snippet: function, full script, Howto, class, Readme.


Select the license you want to use for your snippet.


Select the language of the snippet (if it is language dependent).


Classify your snippet in categories tree.


You should insert here the version of the snippet. For a new snippet, insert 1.0.


Paste here the code of the snippet.

5.4.2. Browsing snippets

You can browse snippets by clicking the Browse link.

You can browse snippets by Language or by Category. The resulting table shows the list of all snippets of the Language/Category. You can click on the snippet number to view the detail of the snippet.

5.4.3. Modifying a snippet

You cannot modify an existing snippet, but you can add a new version of the snippet by clicking on the Submit a new version link on the bottom part of the detail page of the snippet.

Adding a new version does not delete the old version, all previous versions will be available.

5.5. Project Help

This feature allows users to search for help for their projects.

FusionForge Contribution Guide

Roland Mas

Tim Perdue

Guillaume Smet

Reinhard Spisser

1. How to contribute

There are several ways to contribute to the FusionForge project.

  • The first one is to give us a feedback about the software: what you like, what you don't like, features you like to be added in new versions, comments on documentation, etc.

  • You are willing to help develop new features. Give a look at the PM/Task Manager. The three subprojects (Todo, Documentation, Localization) lists the open tasks. You can pick up one of the open tasks and start working on it.

  • If you find a bug, submit a bug to the Bug tracker at http://fusionforge.org/tracker/?group_id=6. If you already solved the bug and are willing to share the fix with us, please add a patch to the bug.

  • If you have developed some new feature, submit a patch to the patch manager of fusionforge. The submitted patch should follow the Coding and Templating standards described in this document.

  • Documentation: there are some parts of FusionForge that are not well documented. Refer to the Task Manager, Documentation subproject for a list of open tasks. You should write the documentation in the docbook format as described in this section.

  • Localization: The user interface of fusionforge is now nearly completely localized. We need translators for the different languages.

    If you like to translate fusionforge to a new, not listed language, please contact us.

2. FusionForge repository

2.1. Anonymous access

You can check out the FusionForge repository from fusionforge.org.

The module you wish to check out must be specified as the <modulename>.


2.2. Modules in repository

The following modules are available in FusionForge repository.


Main module. Contains FusionForge software.


Contains tools which may be useful for FusionForge developers, translators and administrators.

3. PHP Coding Standards

3.1. Introduction

Coding Standards. Live them, love them.

Then come up with a new introduction...


3.2.1. Guidelines

Non-documentation comments are strongly encouraged. A general rule of thumb is that if you look at a section of code and think "Wow, I don't want to try and describe that", you need to comment it before you forget how it works.

  • C++ style comments (/* */) and standard C comments (//) are both acceptable.

  • Use of perl/shell style comments (#) is prohibited.

3.2.2. PHPdoc Tags

Inline documentation for classes should follow the PHPDoc convention, similar to Javadoc. More information about PHPDoc can be found here: http://www.phpdoc.de/

3.2.3. File comments

Every file should start with a comment block describing its purpose, version, author and a copyright message. The comment block should be a block comment in standard JavaDoc format along with a CVS Id tag. While all JavaDoc tags are allowed, only the tags in the examples below will be parsed by PHPdoc.

FusionForge contains a mixed copyright. For files that have been changed since the FusionForge fork, the following header should be used:

 * brief description.
 * long description.  more long description.
 * Portions Copyright 1999-2001 (c) VA Linux Systems
 * The rest Copyright 2002 (c) their respective authors

3.2.4. Function and Class Comments

Similarly, every function should have a block comment specifying name, parameters, return values, and last change date.

 * brief description.
 * long description.  more long description.
 * @author    firstname lastname email
 * @param     variable  description
 * @return    value     description
 * @date      YYYY-MM-DD
 * @deprecated
 * @see

3.2.5. Note

The placement of periods in the short and long descriptions is important to the PHPdoc parser. The first period always ends the short description. All future periods are part of the long description, ending with a blank comment line. The long comment is optional.

3.3. Formatting

3.3.1. Indenting

All indenting is done with TABS. Before committing any file to Subversion, make sure you first replace spaces with tabs and verify the formatting.

3.3.2. PHP Tags

The use of <?php ?> to delimit PHP code is required. Using <? ?> is not valid. This is the most portable way to include PHP code on differing operating systems and webserver setups. Also, XML parsers are confused by the shorthand syntax.

3.4. Templating

In the FusionForge system, PHP itself is used as the template language. To make the templating clearer, template files should be separated out and included once objects and database results are established. Detailed examples are in the docs repository and here.

Variables in the templates are presented surrounded by <?php ?> tags instead of the {} tags that some other template libraries would use. The end result is the same, with less bloat and more efficient code.

3.5. Expressions

  • Use parentheses liberally to resolve ambiguity.

  • Using parentheses can force an order of evaluation. This saves the time a reader may spend remembering precedence of operators.

  • Don't sacrifice clarity for cleverness.

  • Write conditional expressions so that they read naturally aloud.

  • Sometimes eliminating a not operator (!) will make an expression more understandable.

  • Keep each line simple.

  • The ternary operator (x ? 1 : 2) usually indicates too much code on one line. if... else if... else is usually more readable.

3.6. Functions

3.6.1. Function Calls

unctions shall be called with no spaces between the function name, the opening parenthesis, and the first parameter; spaces between commas and each parameter, and no space between the last parameter, the closing parenthesis, and the semicolon. Here's an example:

$var = foo($bar, $baz, $quux);

As displayed above, there should be one space on either side of an equals sign used to assign the return value of a function to a variable. In the case of a block of related assignments, more space may be inserted to promote readability:

$short  = foo($bar);
$long_variable = foo($baz);

3.6.2. Function Definitions

Function declarations follow the unix convention:

function fooFunction($arg1, $arg2 = '') {
    if (condition) {
    return $val;

Arguments with default values go at the end of the argument list. Always attempt to return a meaningful value from a function if one is appropriate. Here is a slightly longer example:

function connect(&$dsn, $persistent = false) {
    if (is_array($dsn)) {
        $dsninfo = &$dsn;
    } else {
        $dsninfo = DB::parseDSN($dsn);

    if (!$dsninfo || !$dsninfo['phptype']) {
        return $this->raiseError();

    return true;

3.7. Objects

Objects should generally be normalized similar to a database so they contain only the attributes that make sense.

Each object should have Error as the abstract parent object unless the object or its subclasses will never produce errors.

Each object should also have a create() method which does the work of inserting a new row into the database table that this object represents.

An update() method is also required for any objects that can be changed. Individual set() methods are generally not a good idea as doing separate updates to each field in the database is a performance bottleneck.

fetchData() and getId() are also standard in most objects. See the tracker codebase for specific examples.

Common sense about performance should be used when designing objects.

3.8. Naming

  • Constants should always be uppercase, with underscores to separate words. Prefix constant names with the name of the class/package they are used in. For example, the constants used by the DB:: package all begin with “DB_”.

  • True and false are built in to the php language and behave like constants, but should be written in lowercase to distinguish them from user-defined constants.

  • Function names should suggest an action or verb: updateAddress, makeStateSelector

  • Variable names should suggest a property or noun: UserName, Width

  • Use pronounceable names. Common abbreviations are acceptable as long as they are used the same way throughout the project.

  • Be consistent, use parallelism. If you are abbreviating “number” as “num”, always use that abbreviation. Don't switch to using “no” or “nmbr”.

  • Use descriptive names for variables used globally, use short names for variables used locally.

    $AddressInfo = array(...);
    for($i=0; $i &lt; count($list); $i++)

3.9. Control Structures

These include if, for, while, switch, etc. Here is an example if statement, since it is the most complicated form:

if ((condition1) || (condition2)) {
} elseif ((condition3) && (condition4)) {
} else {

Control statements shall have one space between the control keyword and opening parenthesis, to distinguish them from function calls.

You should use curly braces even in situations where they are technically optional. Having them increases readability and decreases the likelihood of logic errors being introduced when new lines are added.

For switch statements:

switch (condition) {
    case 1: {
    case 2: {
    default: {

3.10. Including PHP Files

Anywhere you are unconditionally including a class file, use require_once. Anywhere you are conditionally including a class file (for example, factory methods), use include_once. Either of these will ensure that class files are included only once. They share the same file list, so you don't need to worry about mixing them - a file included with require_once will not be included again by include_once.


Note: include_once and require_once are statements, not functions. You don't need parentheses around the filename to be included, however you should do it anyway and use ' (apostrophes) not " (quotes):


4. Templating Standards

4.1. Coding Example

The following code examples demonstrate how all coding on FusionForge is going to be done in the future. The first example shows the “switchbox” page (taken from www/tracker/index.php) - where the various objects are included, instantiated and checked for errors every step of the way.

Once the objects are instantiated, the template file can be included. In this example, the template file is detail.php (example2).

Template page
 * FusionForge Tracker Facility
 * Portions Copyright 1999-2000 (c) The SourceForge Crew
 * Copyright 2002-2004 (c) The FusionForge Teem
 * http://gforge.org/
 * This file is part of FusionForge.
 * FusionForge is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * FusionForge is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with FusionForge; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  US

echo $ath->header(array 
   ('title'=>'Detail: '.$ah->getID(). ' '.$ah->getSummary()));

<H2>[#<?php echo $ah->getID(); ?>] <?php echo $ah->getSummary(); ?></H2>

	<FORM ACTION="<?php echo $PHP_SELF; ?>
		?group_id=<?php echo $group_id; ?>
		&atid=<?php echo $ath->getID(); ?>" METHOD="POST">
	<INPUT TYPE="HIDDEN" NAME="func" VALUE="monitor">
	<INPUT TYPE="HIDDEN" NAME="artifact_id" 
		VALUE="<?php echo $ah->getID(); ?>">
		if (!session_loggedin()) {
		<B>Email:</B> &nbsp;
		<INPUT TYPE="TEXT" NAME="user_email" 
			SIZE="20" MAXLENGTH="40">
			<?php echo date( $sys_datefmt, 
				$ah->getOpenDate() ); ?></TD>
			<?php echo $ah->getPriority(); ?></TD>

		<TD><B>Submitted By:</B><BR>
			<?php echo $ah->getSubmittedRealName(); ?> 
			(<?php echo $ah->getSubmittedUnixName(); ?>)</TD>
		<TD><B>Assigned To:</B><BR>
			<?php echo $ah->getAssignedRealName(); ?>
			(<?php echo $ah->getAssignedUnixName(); ?>)</TD>

			<?php echo $ah->getCategoryName(); ?></TD>
			<?php echo $ah->getStatusName(); ?></TD>

		<H3>DO NOT enter passwords or confidential information 
			in your message!</H3>




5. Documentation

We now use XML Docbook to write documentation. You can read the Docbook Definitive Guide online if you want more information about XML Docbook.

You can use the Serna XML editor to edit the documents.

Documentation is generated by Docbook XSL stylesheets (html output) and DB2Latex XSL stylesheets (PDF output).

6. How to obtain XHTML compliance for FusionForge

The complete XHTML specification is available at XHTML specification at www.w3c.org.

Here is listed a summary of what is needed to be XHTML compliant:

XML declaration

All pages should have the following xml declaration:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html 
     PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
Document must be well-formed

All open tags must be closed, all tags must stay between < and >.

All tags must be lowercase

<HTML> must be converted to <html>.

Empty tags must be closed

No standalone <br> tag is allowed; <br/> must be used.

Attributes must always be quoted

<td rowspan=3> must be converted to <rowspan="3">.

The differences listed here are the most significant differences between HTML and XHTML, there are other, minor differences. For a complete list, refer to the XHTML specification.