Subversion repository
What is SVN?
Generic newbie
In order to coordinate our efforts in a clean and ordered manner, we opted to use one of the major revision control systems to manage the repository that grants life to the Wesnoth-UMC-Dev project. Subversion (a.k.a. SVN) is a fairly robust centralized VCS which provides, amongst other things, a mostly transparent way of managing files and directories in the repository from client systems, seamless tracking of objects' history, and other shiny stuff which we won't describe here.
SVN is used by an important number of major open-source projects at the moment; one of them is the Battle for Wesnoth Project. More information about SVN can be found at their own website, or in the nice and free Subversion Book, which is a highly recommended reading for new add-on developers.
Checking out the repository
The URI that you would use with the svn checkout command or a GUI frontend's equivalent, would be (where <path> stands for a repository tree, e.g. /trunk/Invasion_from_the_Unknown):
-
For anonymous checkouts:
http://wesnoth-umc-dev.svn.sourceforge.net/svnroot/wesnoth-umc-dev/<path>
-
For authenticated checkouts:
https://wesnoth-umc-dev.svn.sourceforge.net/svnroot/wesnoth-umc-dev/<path>
Anonymous checkouts are what a play-tester, lurker, or researcher should use. They do not require any kind of login or membership to the Wesnoth-UMC-Dev project. Authenticated checkouts, however, require the client to use a username and password for a registered SourceForge.net account that is in the members list of the Wesnoth-UMC-Dev project and has been allowed to perform SVN commits (read/write access). Wesnoth-UMC-Dev developers should use authenticated checkouts.
By omitting <path>, you are telling your SVN client to make a checkout of the entire repository, including the /branches, /trunk, and /tags trees and all of its subdirectories. This is certainly not what you want - that way you may be wasting lots of space in your hard disk (hundreds of megabytes), and bandwidth at the SF.net server. Please don't do it unless you have a really good reason to do so! Usually, only admins and half-admins will be interested in having a root checkout.
Repository trees and branches
The Wesnoth-UMC-Dev repository is organized in a slightly unusual manner, which may look extremely alien to you, specially if you are already familiarized with the canonical SVN repository layout. This section describes in detail what each repository tree is meant to be used for, what it contains, etc.
Definitions:
- Hive or supertree or major tree: one of the many ways a repository admin can refer to one of the directories located immediately at the repository's root - that is, /branches, /trunk, /tags or /website.
- Superbranch: a branch that actually contains many inner branches. Every X.Y maintenance branch is a "superbranch" in this sense, since it contains big subbranches corresponding to each add-on located there.
- Tag: a special branch that is generated by using the
svn copy command to copy a whole add-on from a branch or the SVN trunk at a certain revision. It is like a regular SVN branch except that by convention, nobody will commit anything else in it, thus making it reflect exactly the original directory at the original revision from which it was copied. This is used to keep track of add-on releases in SVN - it's not required to use this technique in this repository, but it's strongly encouraged to take it into account.
/trunk
The trunk of this repository reflects the trunk of the Mainline Project's repository, in a certain manner. Any add-ons lying under this hive are expected to work (unless stated otherwise) either with the latest Wesnoth SVN trunk build, or one or more releases of the latest development branch that are actually tagged from the mainline trunk.
By convention, all add-ons here must use the inner _main.cfg syntax to avoid cluttering this /trunk with extra stuff. The directory name in SVN must reflect the actual directory name used by the game to resolve WML and binary paths. This is particularly important for the automated tools used for book-keeping in the repository.
Note: Since _server.pbl files are not allowed here to protect the privacy of the developers, it is recommended that they use the outter Addon_Dir.pbl syntax to avoid committing them by accident.
/branches
As with most SVN repositories, there's the need to fork branches from time to time to concentrate on maintaining an add-on for different Wesnoth version, or to mark a milestone in its development. Sometimes people may want to publish stuff here that doesn't belong to an add-on in particular. In any case, branches are just ordinary SVN directories that may track history from trunk if they were forked "the right way" by using svn copy, or (alternatively, do not use) svn move.
Although many branches are forked for add-ons from trunk, and track trunk's history, there are also branches that do not belong to any add-on and have their independent history. Developers will probably not need to bother with branches other than the X.Y maintenance ones.
X.Y - maintenance branches
The X.Y branches are numbered according to each Mainline stable release series - 1.0, 1.2, 1.4 and so on. Add-ons inside a X.Y branch are expected to work with Wesnoth X.Y and not require features from a newer stable series (e.g. 1.6 vs. 1.4) or a newer development release (1.5.0 vs. 1.4).
When the mainline repository experiences the branching of a new stable release series, the Wesnoth-UMC-Dev /trunk add-ons are branched as well to the new stable series' branch in the repository, by means of svn copy rather than svn move or raw copy, in order to preserve both the visibility of the trunk add-ons in the repository, and their changeset history (which would be lost with raw copies).
Add-ons under a X.Y branch that are also present in /trunk may or may not be actively maintained for the latest development release. Those add-ons that are not being maintained for the development series after branching will usually get a README.1ST file with instructions in their /trunk trees.
resources
Static binary or text resource files for artists, WML coders, sound mixers and repository administrators are kept in this super-branch.
- resources/deprecated_mainline: this branch, maintained by the Mainline Art Director, a trusted Art Developer and the Wesnoth-UMC-Dev administrators, contains artwork that has been dropped from mainline due to style consistency/revision requirements but which is considered perfectly appropriate for UMC authors to use at will.
- resources/admin: maintained by the Wesnoth-UMC-Dev administrators, this tree contains files used for repository administration, maintenance and book-keeping, that are not executable or interpreted code.
- resources/...: other branches are considered maintainer-less unless otherwise specified in any plain text files that they may contain.
testing/X.Y
This area is reserved for dummy/stub add-ons intended specially for testing new Wesnoth features, providing reliable bug test-cases to the mainline project, or some random administrative weirdness. The only people who may be ever interested in it are the particular authors, the repository administrators, or the Mainline Development team.
In this tree you'll find subtrees of the X.Y form, where X is a Wesnoth major version number (e.g. 1), and Y a minor version number (e.g. 6), representing the number of the stable branch for which the add-ons were written. If they were intended as bug test-cases for the development branch, they will be under the directory representing the stable branch that will be forked from that development branch - e.g. 1.6 for 1.5.
Add-on directories under the subtree will often have self-explanatory names, such as "Bug12404_Test_Case" or "Standing_Anim_Flickering". For book-keeping purposes, it is recommended, as usual, not to remove any directories in this tree.
maintenance-toolchain
This branch is maintained by the repository administrators, and contains several scripts used for basic repository and add-on maintenance, sanity checking and processing. Most of them are written for the Bourne-again Shell, although there are also some midly complex Perl and Python programs sitting around. The scripts in this directory usually have some sort of documentation embedded as commented blocks at the beginning of the files, or in the form of a --help command-line switch.
This branch contains WML tools not in the mainline repository, made by UMC developers for UMC developers. Each tool has its own subtree(s) and maintainer(s).
irc-bots/shikadibot
(See also: Shikadibot Model 0314)
Our IRC channel needed the services of a custom bot to help in discussing commits, providing newbies with acronym definitions, and providing some amusement to a bunch of geeks without /(girl|boy)friends/;.
shadowmaster/ShikadiLord and AI0867 are in charge of maintaining the IRC bot of the Wesnoth-UMC-Dev project in this branch.
This hive is dedicated to keeping record of add-on release/milestone tags under trees named according to /trunk and the X.Y maintenance branches. Although add-on authors are not required to take advantage of the SVN tag idiom to keep track of what SVN revisions they use to fork their official release packages, we strongly encourage them to learn to use the tags idiom for add-ons released in a regular basis.
Generated in 0.002 seconds.
This page was last modified on Tue Mar 23 13:25:55 CET 2010.
