Programming:How to use SVN

From Post-Apocalyptic RPG wiki

Jump to: navigation, search

Subversion.png This article is an SVN how-to!

SVN how-tos serve as documentation how the Subversion version control software is utilized by the developers in general or how it's used by a specific development department.

This article describes programming-department-specific ways of working with Subversion.

Contents

Distributed version control

While we're currently using a centralized Subversion repository for version control, switching to distributed version control is planned in the long run. If you're interested in the details, check out Distributed version control software.

Repository structure

  • branches: branches for changes that should not go into trunk right away
    • active: branches under active work that introduce larger changes that would likely break trunk
    • historic: archived branches not under active work anymore
  • tags: tagged releases
  • trunk: the main development branch
    • game: the game itself, including ingame assets
    • tools: all kind of (asset creation) tools

Guidelines

Branching

This section covers guidelines and philosophies we apply when working with branches. Working with branches is something that might seem scary to some, especially in a centralized version control environment due the problematic merging process. These guidelines are meant to make the merging process as painless as possible. If you're interested in syntax details, check the section below.

When to use a branch

As a rule of thumb: whenever you plan to prototype changes that would break trunk, create a branch. This way you can test your changes without having to worry about breaking the working copy of everyone else.

How to use a branch

New branches reside in branches/active/<branch_name>. branches/active is meant for all branches that are actually being worked on. Choose a branch name that is representative for what you try to achieve with the branch.

Some good examples:

  • branches/active/maploader_rewrite
  • branches/active/alternative_yaml_parser
  • branches/active/new_build_system

Some bad examples:

  • branches/active/test
  • branches/active/work
  • branches/active/<developer_name>

Branch names shouldn't make any reference to who works on the branch. We want to avoid that developers are marking off their territory. While branches have active maintainers who are primarily working on them, these maintainers do neither own the branch nor the code within it!

Keeping branches in sync with trunk

Due the way Subversion works, merging back branches can be quite a frustrating experience. This is mainly caused by branches and trunk growing further and further apart which will lead to a lot of merge conflicts down the line. Therefore you should sync your branch with trunk on a regular basis. This way you can ensure that the branch is not growing apart from trunk beyond what is absolutely necessary. This will ease merging back the branch into trunk later.

Branch review

You should encourage other developers to regularly take a look at your branch to get feedback. This is a good way to ensure you're running in the right direction before writing a lot of code that might turn out to be wasted time and effort.

Merging back the branch

Once you're happy with the state of the branch, request extensive branch review by the other developers. Also make sure that no unit tests are failing and that you can actually run the game. Once the branch review process has been completed, we're ready to merge back the branch to trunk.

There are two basic approaches to this:

  1. Merge branch into trunk
  2. Branch becomes new trunk

The first approach is prefered and should work fine 95% of the time; especially if you synced your branch with trunk regularly. In this case, merge your branch with trunk, commit the changes to trunk and move your branch to branches/historic after that.

In 5% of the cases, especially if you have been working on really substantial revolutionary changes, your branch will have grown apart from trunk despite syncing efforts. In this case the old trunk gets moved to branches/historic and the revolutionary branch gets moved to trunk.

Common tasks

Command Line SVN

Creating a branch

Syncing a branch with trunk

Merging a branch back to trunk

TortoiseSVN

Creating a branch

Syncing a branch with trunk

Merging a branch back to trunk

Personal tools