Project management in the NBIC Development Environment
The NBIC Development Environment provides software projects with tools to manage source code, documentation, and communication. For this, existing software tools are configured so that they supplement eachother. These tools are
- Trac ( http://trac.edgewall.org/)
- Mailman ( http://www.gnu.org/software/mailman/)
- Subversion ( http://subversion.apache.org/)
This page provides basic information on how to use these tools, aimed at the project managers (owners).
A note about project names
You may choose to specify a project name with uppercase characters, but since some properties, such as mail addresses, are not case sensitive, certain resources will not reflect the uppercase characters.
The website of a project is hosted using Trac, and basic usage is explained in the TracGuide. The initial Trac configuration is almost entirely standard, with two modifications:
- the Wiki homepage (WikiStart) is replaced with one that contains information pertinent to the NBIC Development Environment.
- the project initiator receives full privileges on the Trac instance, allowing him or her to configure it to the projects needs.
Modifying the Trac configuration is done by logging into Trac, and accessing the Admin component, which is only available to users with full privileges (i.e. project owners). The Admin component initially provides two groups of properties which can be modified. The permissions in the general section and the ticket system are the most important. The properties under Basic Settings are largely ignored due to the fact that the NBIC Development Environment maintains these data separately. For configuring plugins, please refer to the documentation of the plugin itself.
NB: the Admin interface may display other components if more plugins are added to Trac.
Trac implements a permission system through which access to components and functions are controlled. These permissions can be assigned to individual users or user groups. Permissions work cumulatively, in that each user receives the permissions of all groups they are a member of, and all permissions assigned individually. In particular:
- Any visitor to the project website is automatically a member of the group anonymous, or reversely, any permissions assigned to this group are applied regardless of authentication.
- Any user logged into Trac is automatically a member of the group authenticated, and authentication is restricted to project members.
- The project managers (owners) have full privileges (TRAC_ADMIN). Assigning TRAC_ADMIN privileges to a user should be done by making them owners of the project in the project administration interface.
Besides these groups, new groups can be created to group certain permissions, but note that these new groups can only consist of project members. An explanation of all available permissions can be found on the TracPermissions page.
NB: project managers are strongly recommended not to assign any privileges that allow modification of information to the group anonymous.
Tickets in Trac can gather various relevant information, and represent different states. What this information and these states are can be partly configured in the Admin component. The following properties of the ticket system can be configured:
- the components the software consists of, such as 'documentation', 'core application', 'libraries', and so on.
- the milestones defined for the development of a project, which correspond to the milestones visible in the roadmap.
- Priorities, resolutions, severities, ticket types, versions
- additional properties that can be assigned to a ticket.
The project is set up with many of Trac's fairly sane defaults, but some of these properties have placeholder values. For most properties removing all available options will result in their removal from the ticket form. In general, defining sensible ticket properties is an effective way of organising feedback.
Project mailing lists are provided by Mailman. When a project is set up, the project initiator receives a password that provides access to the mailman administrative interface. If you're administering a project that you haven't initiated, you will have to ask the initiator for access. The URL of the administrative interface of each mailing list is also communicated to the project initiator, but the generic format is
where you have replace <listname> with the actual name of the list in lower case.
The initial configuration of each list is the default mailman configuration, with two exceptions. The lists are not advertized in any mailman generated pages, and the list archives are not accessible to people that haven't subscribed to the lists themselves. These properties can be modified by the list administrator(s).
The default subscription policy for any mailing list is that anyone can subscribe by visiting the mailing list front page. The exception is the <project>-devel list, which is only accessible to project members. Therefore, list membership is maintained through the project administration interface, and modifications to the membership list in the Mailman administration will be reverted when the project information is updated. On a related note, the <project>-devel list page has no subscription form.
You can set up a new list by creating a ticket. Please provide information such as the name of the project, the name of the list you wish to create (only lowercase alphanumeric characters and dashes allowed), and the mail address of the initial owner of the list. Removing a list is best done by just removing any reference to its existence, so that all list data are preserved in case in needs to be revived. If you are adamant that a list should be deleted, please create a ticket and specify the project and list name. Please note that your requests for list creation and deletion will only be acted upon when submitted by one of the project managers.
What you need to know in advance:
- The subversion setup is basic, in that not even conventional trunk, tags, and branches directories are created. In case you prefer to have these present, be sure to add these to the source tree, for example by entering (replace <project> and <projectdir> with appropriate values):
svn co <project> <projectdir> cd <projectdir> mkdir trunk tags branches svn add trunk tags branches svn ci -m 'add basic repository structure'
- In the administrative interface you can select to allow anonymous access to the source code repository. The consequence of selecting this is that users do not need to have an account to check out the source code. Committing to the repository always requires membership, which you can manage in the project administration interface.
Copying (part of) another repository
In some circumstances it is desirable to copy the code from a source repository to another repository, while preserving the revision history. To this end, the utility svnsync can be used. The subversion repositories in the NBIC environment are configured to allow synchronization, but there are some caveats:
- read access to the source repository and write access to the destination repository are required
- the destination repository must be empty for the initial synchronization
- repeated synchronizations on the destination repository can only be done if it hasn't been modified directly
Copying a repository using svnsync is a two-step process. First, the destination repository must be prepared for synchronyzation:
svnsync init --source-username <user> --source-password <pw> --sync-username <user> --sync-password <pw> <destination> <source>
The options provide authentication for the source and destination (sync) repositories. The destination is the URL of the root of the repository that will receive the copied data, and the source is the URL of the root of the source repository. As of subversion 1.5 it is possible to specify a subdirectory of the source repository to copy only part of the source repository. If the initialization is succesful, svnsync will indicate this with
Copied properties for revision 0
Now the actual synchronization can be done:
svnsync sync --source-username <user> --source-password <pw> --sync-username <user> --sync-password <pw> <destination>
The revisions will be copied one by one, which may take some time if there are many revisions in the source repository.