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:
- Version12Plan for 1.2 planning.
- Version14Plan for 1.4 planning.