Subversion/CollabNet integration

This document is intended for users of CollabNet Enterprise Edition who are already reasonably familiar with the core Subversion product, and have read the main Subversion Book, Version Control with Subversion. It also assumes that the readers have some degree of familiarity with CollabNet—that they have previously used CVS-backed CollabNet projects.

Repository layout

Subversion uses an independent Subversion repository for each project. When the project is first created, an new repository is made with a default layout that follows the recommendation of the Subversion book. In essence, the repository is a single "project root" (as discussed in "Choosing a Repository Layout" in the Subversion book):

      /branches/
            README

      /tags/
            README

      /trunk/
            www/
               index.html

      README

As with any Subversion repository, we recommend that your project store its main codebase in /trunk, and then use the svn copy command to copy the /trunk directory to the /branches and /tags area to create branches and tags.

"Live" project home page

The /trunk/www area is a special directory, just as it is with CVS-backed projects. If you've selected the "use project index.html" option in your project's settings, then this directory represents your project's main website. Any commits to this area will cause an immediate update to the front page of your project.

Commit email

Whenever a commit is made to your repository, an email is sent to commits@yourproject.domain. It is standard procedure to have the project members subscribe to this list to increase their awareness of each other's activities.

Subversion Client Authentication

Note: The information in this section assumes that your site does not require SSL client certification. If your site uses SSL client certificates, see Subversion client authentication using client certs.

Your repository's URL is constructed by adding /svn/projectname after your project's main URL. We recommend that you check out /svn/projectname/trunk, not the root of the repository:

$ svn co http://project.domain/svn/project/trunk project

Authentication realm: <http://project.domain:80> CollabNet Subversion Repository
Password for 'username': XXXXX

A  project/
A  project/www
A  project/www/index.html
Checked out revision 1.

Subversion clients must supply a valid CollabNet username and password to access the repository. If your CollabNet site is configured to use https:// instead of http://, then you must also use https:// to access the Subversion repository. This mode of operation securely encrypts all messages over the connection, including your password.

After the Subversion client has successfully authenticated, it will automatically attempt to cache the credentials in the user's run-time config area. To prevent this on-disk caching (or to simply learn more about this feature), refer to "Client Credentials Caching" in the Subversion book.

CollabNet Server Authorization

One of the nicer features of Subversion/CollabNet integration is the ability to use CollabNet "roles" and "resources" to control different users' access to specific paths in your repository. To learn about CollabNet roles in general, see this documentation.

Just as with CVS-backed projects, users may request a number of standard roles in your project. The roles below are the most relevant to version control:

Observer
Read-only access on the entire Subversion repository.
Content Developer
Read/write access only on /trunk/www. Cannot read or write any other part of the repository.
Developer
Full read/write access on the Subversion repository.
Project Manager or Project Owner
Same version control permissions as "Developer", but with extra privileges in other parts of CollabNet.

Additionally, Project Owners may wish to create their own resources and roles specific to their project. Because Subversion presents all branches and tags in ordinary filesystem space, it's possible to selectively restrict access on branches and tags, which is a great improvement over CVS.

For example, you might define Developer roles that allow write access to every part of your repository except the /tags directory, and then create a special "Release Manager" role with special permission to create new tags. There are limitless possibilities.

Repository Browsing

You can use the Version Control - SCM link in your project's navigation bar to browse the history of your files. Subversion is not quite the same as CVS, however, so there are a few differences when browsing an Subversion repository:

Integration with Project Tracker

If your Subversion project is configured to use Project Tracker (PT) instead of Issue Tracker, then some extra degrees of integration are available. Project Owners can adjust three integration settings between Subversion and PT on the Tool configuration page.

The project can be configured to allow Subversion commits to append commit information to PT artifacts. If the commit log-message mentions a specific PT artifact, then the following things will be appended to the artifact:

In order to trigger automatic appending, the commit log message must contain a string of characters that matches a Project Tracker artifact ID: specifically, the string needs to be 1 to 4 letters, followed by a number of digits. Any matching strings are automatically considered "candidate" Project Tracker artifacts that might be appended.

Apart from the above rule, any ID that has the text "Issue", "Bug´┐Ż or "Artifact" followed by a number will be identified as a valid ID if it exists in the project as a Project Tracker artifact ID.

Artifact type names in use in a project can also be used, so if the project has Defect and Requirement artifact types, then an artifact ID in that project may be referred to as Requirement 1 or Defect 3. So if there are Defect artifacts in a particular project which has artifacts named SC1, SC2 and SC3, but your commit message has the text Requirement 3, it will still be treated as a valid ID with hyperlinks.

SCM can also be configured to force all commit log-messages to mention at least one PT artifact. If a commit message fails to do this, the entire commit will be rejected. This feature can be further configured to require that the mentioned artifact ID be "owned" by the same person making the commit. Both of these settings can be used to enforce specific version control policies in your project.