The Debian Games Team currently uses either git or svn to help in maintaining packages. This page will help you get started in using either git or svn repositories.

Scheme

Most of the packages are independent from each other. In svn, a [trunk,tags,branches}/<package> scheme is used with only the debian directory stored. The .orig.tar.gz files in such a case are stored in /var/lib/gforge/chroot/home/groups/pkg-games/htdocs/tarballs in the alioth servers. They can be accessed online at http://pkg-games.alioth.debian.org/tarballs. In git, each package has it's own repository. The contents of the orig tarball are stored directly within each package's repository, inside the 'upstream' branch. The pristine-tar program can be used to regenerate an orig tarball from the upstream branch.

Setting up

The first thing to do is get an account on alioth.debian.org. Visit the following link.

The next step is to join the team. Visit the Alioth page for the team and click on "request to join".

Next, you will need an ssh key for each computer you plan on working on packages with. If you don't have a key on a particular system, create one.

$ ssh-keygen

This should have created an RSA key for SSH protocol 2 by default. Upload the contents of your public keys (~/.ssh/id_rsa.pub) to your account in Alioth. To do this, copy the contents of each public key for your machines and paste them at the following link.

Next, create an SSH configuration file (~/.ssh/config) for your user profile to work with the alioth servers. Here's how to do the following in a terminal session.

$ cat >>~/.ssh/config <<EOF
Host svn.debian.org
        User <username>

Host git.debian.org
        User <username>

Host alioth.debian.org
        User <username>
EOF

Now you should be able to logon from each of your machines by doing the following.

$ ssh svn.debian.org
$ ssh git.debian.org
$ ssh alioth.debian.org

Note: There's usually a one hour delay when uploading your ssh public keys. During this delay, you can still login with your password.

Git

See Games/VCS/git.

mr

The mr command can be used to checkout, update, and commit to multiple repositories. In the pkg-games svn repository, is a packages/trunk/.mrconfig file that configures mr for all the repositories used by the games team.

New git repositories should be added to this .mrconfig file.

To use it, install the mr package, and create a ~/.mrconfig file letting mr know about the pkg-games svn repository. In this example, it will be checked out to ~/src/packages/games, but you can modify to suit. If you already have a pkg-games svn checkout, you can change the directory to point to that.

[src/packages/games]
chain = true
checkout = svn co svn+ssh://svn.debian.org/svn/pkg-games/packages/trunk games

Then run "mr checkout", which will checkout the svn repository into ~/src/packages/games.

A second "mr checkout" (necessary because of bug #447553) will checkout the additional git repositories, into subdirectories of ~/src/packages/games/.

Now you can use mr to act on all configured repositories at once.

Update all repositories:

% mr update

Get status of all checkouts:

% mr status

List all repositories that mr knows about:

% mr list

Or even commit changes in each repository:

% mr commit

If you've added a new git repository in ~/src/packages/games/<foo> and are in that directory, you can have mr automatically add it to the pkg-games .mrconfig file by running "mr register". (Don't forget to commit the file.)

SVN

The SVN repository may be browsed online using a browser via the following link:

http://svn.debian.org/wsvn/pkg-games/packages/trunk/?rev=0&sc=0.

The base URI of the repository for authorised SVN access is

svn+ssh://svn.debian.org/svn/pkg-games/

To import your package to SVN

    apt-get install svn-buildpackage

    # Import only the files that are touched
    # by the .diff.gz
    svn-inject -o -l 2 <package_dsc_file>.dsc \
    svn+ssh://svn.debian.org/svn/pkg-games/packages/

NOTE: The -l 2 option for svn-inject specifies layout two. You must have svn-buildpackage (>= 0.6.16) to use this option. Another thing to note is bug 411666 - /usr/bin/svn-inject: initial checkout fails. If your package doesn't exist in the SVN, this bug may affect you. The best thing to do is to use svn-buildpackage (>= 0.6.22).

In very seldom cases (like dead upstream) you would probably want the full source in svn instead just of the contents of the .diff.gz. In that case, remove the -o parameter from the command.

Uploading the Source Tarball

scp <package_name_and_version>.orig.tar.gz \
alioth.debian.org:/var/lib/gforge/chroot/home/groups/pkg-games/htdocs/tarballs/

svn co \
svn+ssh://svn.debian.org/svn/pkg-games/packages/trunk/<package_name>
cd <package_name>
svn propset svn-bp:origUrl \
"http://pkg-games.alioth.debian.org/tarballs/<package_name_and_version>.orig.tar.gz" debian
svn ci -N debian -m "origUrl property set for <package_name_and_version>"

To Checkout A Project

    svn co \
    svn+ssh://svn.debian.org/svn/pkg-games/packages/trunk/"packageName"

To build

    # Place the .orig.tar.gz in ../tarballs/

    # Build the package
    svn-buildpackage -rfakeroot

    # or, if you want to make it the build before uploading, and
    # have svn-buildpackage make a svn tag for you
    svn-buildpackage --svn-tag -rfakeroot

    # if you have local changes in your working copy and want to
    # run a test-build, use the `--svn-ignore' switch like so:
    svn-buildpackage --svn-ignore -rfakeroot

    # example for freecol:
    $ svn proplist -v debian
    Properties on 'debian':
      svn-bp:origUrl : http://pkg-games.alioth.debian.org/tarballs/freecol_0.7.2.orig.tar.gz
      mergeWithUpstream : 1

To build using pbuilder

pbuilder is a great tool to check that your package will build in a basic Debian system with the proper build-dependencies. It's also useful in avoiding having to install a package's build-dependencies on your system.

First, you will have to setup pbuilder on your system. The HOWTO at https://wiki.ubuntu.com/PbuilderHowto provides a good guide and some good tips in setting up pbuilder.

Afterwards, it should be just a matter of using the --svn-builder option. For example, to use pdebuild and ignore all .svn directories, use:

svn-buildpackage --svn-dont-clean --svn-builder='pdebuild --debbuildopts "-i\.svn/ -I.svn"'

Alternatively, you can use a simple script as svn-builder. Here's a script taken from the examples from the git-buildpackage package that's been modified to work in the case of svn-buildpackage.

#!/bin/sh
# 
# pbuilder helper from git-buildpackage
# use this as "svn-builder" in ~/.svn-buildpackage.conf
set -e

# pass all options to dpkg-buildpackage:
pdebuild $PBUILDER_OPTS --debbuildopts "-i\.svn/ -I.svn $*"

Create a file called svn-pdebuild under /usr/local/bin and add the contents of the above script into the file. Then you can just run:

svn-buildpackage --svn-builder=svn-pdebuild --svn-dont-clean

You can also specify svn-builder using a configuration file at ~/.svn-buildpackage.conf. Create a file at ~/.svn-buildpackage.conf and add this snippet.

svn-builder=svn-pdebuild
svn-dont-clean

Then just run:

svn-buildpackage

Finally, if you need to specify more options for pdebuild's --debbuildopts option, just add them in like you would normally do for --debbuildopts. Here's an example that works using the method that uses ~/.svn-buildpackage.conf.

svn-buildpackage -sa -us -uc

svn-buildpackage will pass any options it doesn't recognize onto whatever command was specified as svn-builder. If you need to specify options for pbuilder, assign each option to PBUILDER_OPTS.

NOTE: The svn-dont-clean option is used since the Debian Games team SVN won't contain upstream source files.

To release

In order to have a lower threshold for someone to step in to help in for a game, some guide lines should be followed when working with the games maintained in our repository.

Thus, here are a few simple rules that should make our lives a little better.

    # example: boson-base changelog between the released version 0.11-2 and the to be relased 0.11-3

    $ head -n1 boson-base/trunk/debian/changelog
boson-base (0.11-3) UNRELEASED; urgency=low

This can be acomplished if svn-buildpackage is used when handling releases.

Before releasing, please check that your package is lintian clean. Automatic checks are done on our SVN tree by the Games/Autobuilder.

Due to bug 433536 in svn-buildpackage (which should be fixed in release 0.6.22), the "tags" directory was not created for packages injected using layout 2, the layout used by our team. If you are using an older version of svn-buildpackage or not at all, please make sure that the tags directory for your package exists under the "tags" directory in SVN:

svn mkdir svn+ssh://svn.debian.org/svn/pkg-games/packages/tags/<package>

Then you will be able to tag a release.

    # make a final build for a package
    $ svn-buildpackage --svn-tag

If your package is accepted into the Debian archive already, you can save some time by just tagging the release.

svn-buildpackage --svn-tag-only --svn-noautodch

The --svn-noautodch will prevent the changelog from being tagged UNRELEASED.

Possible problems

git import-orig dch error

When using git import-orig, there is a chance you'll receive an error similar to this one.

dch: fatal error at line 963:
New version specified (1.4.8.dfsg1-1) is less than
the current version number (1.4.8.dfsg1-1)!  Use -b to force.
dch returned 25
Dch failed.
Import of ../../build-area/ogre_1.4.8.dfsg1.orig.tar.gz failed

This will happen if you omit the --no-dch option while running git import-orig and the version in the changelog is at the version of the orig tarball that's being imported.

git import-orig pristine-tar error

It's possible you may receive an error such as this.

pristine-tar: more than one ref matches "upstream":
5f4736c83ea06e9b479a35f25d997b73713306b9 refs/heads/upstream
a8c20d823bc28bb8f6d127e301390bed06e49169 refs/remotes/origin/upstream
/usr/bin/pristine-tar returned 255
Couldn't run '/usr/bin/pristine-tar'

This is caused by git import-orig (or any of the git-buildpackage tools) supplying the parameter "upstream" to use when running pristine-tar commit instead of using the default refs/heads/upstream or supplying a tag object instead and you cloned a git repository. You will have to omit the --pristine-tar option from the git-buildpackage tools and use pristine-tar manually. See 481806.

General Rules

See Also