Warning: Can't synchronize with the repository (Couldn't open Subversion repository /home/crystal/scm/crystal: SubversionException: ("Expected FS format between '1' and '3'; found format '4'", 160043)). Look in the Trac log for more information.

Introduction

This page is meant to give an overview as well as practical advices about Crystal Space code source management in its  Subversion repository.
If you're not familiar with Subversion (aka. SVN), please check the  SVN Book and the  Subversion FAQ.

Subversion, Version and Revision

Subversion is used to maintain Crystal Space source code repository, which is following the usual convention of having:

  • a trunk, which is the latest development version, ie. where day-to-day general changes take place.
  • a few branches, where changes toward a specific purpose are made.

A version is a coherent state of the software which is often identified using a version number, but is not the same as a release.

A revision is a single piece of change (aka. commit) applied to the source code repository using the subversion client.

Where, How ?

The repository root URL is  https://crystal.svn.sourceforge.net/svnroot/crystal

Apart the famous trunk which URL is  https://crystal.svn.sourceforge.net/svnroot/crystal/CS/trunk, Crystal Space uses branches for mainly 3 purposes:

  • features: experimental or big changes are made in so-called feature branches.
  • release: at some point, trunk is copied in a new branch named after the new version to be released.
    All the stabilisation is then done in that branch, with fixes generally being merged from trunk to that branch.
  •  GSoC: students are given a branch, where they can work without risking breaking anything. A GSoC branch is just a special case of a feature branch.

The different branches can be browsed at  https://www.crystalspace3d.org/trac/CS/browser/CS/branches.

Keeping track of changes

There's a useful tool called Trac, which helps at bug tracking, task management, release management, as a wiki, or simply keeping an eye on what happens in the repository. Its address is:

One of the most useful Trac view is the  Timeline (also see  CEL Timeline).

Using Subversion

The first step as a Subversion user is to check out a working copy of the source code from the repository, be it the trunk or a specific version or branch.

Committing changes

As much as possible, please don't commit different unrelated changes in a single changeset, especially if you're working on trunk.
Doing so might increase the difficulty of merging a needed change in a release branch.
If a changeset implies the change of some generated file(s), it is generally better to commit the regenerated stuff later, in a distinct changeset.

Merging changes

The  svnmerge.py tool is now prefered over svn merge to merge changesets from one branch or trunk to another.
Not only is it useful to avoid merging changesets twice, but it also ease merging multiple changesets considerably.
It's usage implies that:

  • svnmerge.py init has to be run on the branch where changesets are to be merged.
  • there are no local modifications of the working copy when svnmerge.py is run.

When committing after using svnmerge.py, please use the generated svnmerge-commit-message.txt as comment. For example, invoke:
svn commit -F svnmerge-commit-message.txt

Managing a feature branch

_TODO_

Managing a release branch

See FuturePlanning for general guidelines, as well as version-specific pages, like: