Working with SVN

From Armagetron

Don't you worry, working with subversion is, for everyday operation, just the same as working with CVS. In fact, rule 1 is that command line users get by pretty well by just replacing the cvs command with svn. Once you have a checkout that is.

Commnads

Checkouts

The basic command to get a checkout is

svn co https://svn.sourceforge.net/svnroot/armagetronad/<path> <target>

Where <path> is a yet to be specified subpath in our repository (you usually don't fetch the whole thing) and <target> is the name of the directory where the checkout will reside in. In SVN, branches and tags are managed simply as different paths in the repository. So your choice of <path> determines which branch or which tag and which module you're getting.

Layout

Subject to change with notice, <path> is organized like this for core modules:

<path> = armagetronad/<brag>/<module>

<brag> stands for "branch or tag" and is either "trunk" for the trunk, "branches/<branch name>" for branches and "tags/<tag name>" for tags. Branch and tag names don't have the same restrictions as in CVS (no dot, start with letter), so a typical branch name would be 0.2.8, a typical tag name 0.2.8.2_rc1. Note that 0.2.8.0 is both name of a tag for version 0.2.8.0 and of the branch leading to that version.

<module> is the module name. It's just "armagetronad" for the core source and "build/<former cvs name - armagetronad>" for the auxiliary modules armagetronad_build* and armagetronad_winlibs. the build/ part will be missing on historical branches (0.2.8 and earlier), and during the first days, also on the trunk, because the sources there expect all modules to be checked out into the same level.

Common examples: To get the trunk sources, you would do

svn co https://svn.sourceforge.net/svnroot/armagetronad/armagetronad/trunk/armagetronad armagetronad

To get the release building module on its side to make a release, you do

mdkir build
svn co https://svn.sourceforge.net/svnroot/armagetronad/armagetronad/trunk/build/build build/build

or in the first days, simply

svn co https://svn.sourceforge.net/svnroot/armagetronad/armagetronad/trunk/build build

To get the same for one of the earlier branches, you do

svn co https://svn.sourceforge.net/svnroot/armagetronad/armagetronad/branches/0.2.8/armagetronad armagetronad
svn co svn co https://svn.sourceforge.net/svnroot/armagetronad/armagetronad/branches/0.2.8/build build

Sounds complicated and cumbersome for many modules? Just check out everything from the trunk with

svn co https://svn.sourceforge.net/svnroot/armagetronad/armagetronad/trunk trunk

Whether you choose the name of the checkout to be the same as the last bit of the repository path is entirely up to you, but it's a good idea if you want to avoid confusion.

Selecting branches is still cumbersome that way. That's why we're pondering to introduce

Workspaces (proposal)

Workspaces are parts of the repository that use a special subversion feature called externals to give you the checkouts you need for a specific task. You'll be able to get your workspace with

svn co https://svn.sourceforge.net/svnroot/armagetronad/workspaces/<os>/<branch> <target>

or, if you want all workspaces,

svn co https://svn.sourceforge.net/svnroot/armagetronad/workspaces/<os> workspaces

<os> is your operating system type, either "unix" or "windows". OS X probably counts as "unix". The workspaces will contain only those modules needed; the unix workspace will be missing the visualc, code::blocks and winlibs directories, and the windows workspace the build and build_eclipse modules.

<branch> is a symbolic branch name. We won't be making workspaces for every branch, only for those actually in use. <branch> can be one of "trunk" for the trunk, "bugfix" for the branch leading to the very next release, and "stable" for the branch leading to one of the releases after that one.

We'll be updating the workspaces to always point to the branches that meet the description. "trunk" will always be the trunk. Right now, "stable" would point to 0.2.8, and "bugfix" to 0.2.8.2, but that one is still managed in CVS, so "bugfix" will point to 0.2.8 as well. Changes into the "future", for example pointing "bugfix" to a newly creates 0.2.8.3 branch, will be done without big announcements; your checkout of the workspace will make the update automatically, taking with it all uncommitted changes as if it was a regular update. Changes that mess with the module structure will be announced; with those, uncommitted changes may get lost.

There are simple rules which change should be done in which of the workspaces:

  • changes that are absolutely super-surely improvements in the short and long term go to "bugfix". Critical bugfixes, security fixes or zero risk bugfixes (adding NULL pointer checks, removing obsolete documentation) are the most common candidates.
  • changes that are likely to be improvements in the middle term (think four weeks) and long term, but may have small startup difficulties go to "stable". All bugfixes that don't qualify for "bugfix" go here, as well as small features that were forgotten in the roadmap of a release series (anticipating Luke's protest here).
  • Everything that is likely to be a long term improvement goes to "trunk". This is the default place for new features.
  • Everything where it is not sure whether it is an improvement or not should go into an experimental branch that may or may not be merged back into the trunk. Workspaces for those are created on demand.

Name alternatives instead of trunk/stable/bugfix:

  • trunk/branch/twig (following the tree metaphor)
  • trunk/next/upcoming (depicting the release they're leading to)
  • long/mid/short (for longterm, midterm and shortterm quality focus)
  • gas/liquid/solid (states of matter representing the stability, easily extended to "plasma" for experimental stuff)

Private space (proposal)

We'll have a section in the repository reserved for private use; personalized copies of workspaces can go there, or branches where only one or two developers work on. The sub-category path would be "private/<user name>".

If a branch becomes more mainstream, it can be moved in with the main project.

At some point, private branches in the repository may be available to non-developers on request.