Programming:How to use SVN
From Post-Apocalyptic RPG wiki
This article describes programming-department-specific ways of working with Subversion.
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.
- 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
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:
Some bad examples:
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.
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:
- Merge branch into trunk
- 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.