Differences between revisions 78 and 93 (spanning 15 versions)
Revision 78 as of 2009-09-12 09:53:24
Size: 12897
Editor: jmtd
Comment: excise git stuff
Revision 93 as of 2017-10-15 13:56:54
Size: 5959
Editor: coringao
Comment:
Deletions are marked like this. Additions are marked like this.
Line 8: Line 8:
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. 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 /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.
Line 47: Line 47:
== Git ==

See [[Games/VCS/git]].
Line 53: Line 49:
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. The mr command can be used to checkout, update, and commit to multiple repositories. In the svn+ssh://svn.debian.org/svn/pkg-games/mrconfig, is a .mrconfig file that configures mr for all the repositories used by the games team.
Line 57: Line 53:
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. To use it, install the mr package (in Debian Stretch the package is myrepos), 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. Note that the last field on the 'checkout' line ('games' in this instance) should match the last field of the configuration path ('src/packages/games').
Line 65: Line 61:
Then run "mr checkout", which will checkout the svn repository into ~/src/packages/games. Then run "mr checkout", which will checkout the svn repository into ~/src/packages/games. The checkout will be approximately 120MB.
Line 67: Line 63:
A second "mr checkout" (necessary because of bug #447553) will checkout the additional git repositories, into subdirectories of ~/src/packages/games/. Next set up the shared games team .mrconfig. In your ~/.mrconfig, add the following entries.

{{{
# Update the games team mrconfig
[src/packages/games-mrconfig]
checkout = svn co svn+ssh://svn.debian.org/svn/pkg-games/mrconfig games-mrconfig
update = svn up ; cp ~/src/packages/games-mrconfig/.mrconfig ~/src/packages/games/.mrconfig
}}}

An 'svn up' will pull down two files into the new directory - a README and the .mrconfig file.

Before doing the final checkout (using mr), you need to setup a ~/.mrtrust file. This is supported in all versions of mr from 0.42, and is required for chained checkouts from 1.00 (January 2011). The contents of the file should be a series of paths (one per line) to .mrconfig files. In our case, it will be one line:

{{{
/home/YOURNAME/src/packages/games/.mrconfig
}}}


Two more "mr checkout" runs (necessary because of bug #447553) will checkout the additional git repositories, into subdirectories of ~/src/packages/games/. (As of December 2011, the full debian-games repo was approx 6.5GB).
Line 73: Line 87:
{{{
Line 74: Line 89:
}}}
Line 77: Line 93:
{{{
Line 78: Line 95:
}}}
Line 81: Line 99:
{{{
Line 82: Line 101:
}}}
Line 85: Line 105:
{{{
Line 86: Line 107:
}}}
Line 89: Line 111:
== Git ==

See [[Games/VCS/git]].
Line 91: Line 117:
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 DebianBug: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 ===

 * Upload the orig tarball for every package that you maintain to the pkg-games' canonical place for them. They will be uploaded and viewable from http://pkg-games.alioth.debian.org/tarballs/

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

 * Next, set the property svn-bp:origUrl of the debian folder of the package to point to the corresponding orig tarball

{{{
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.

{{{#!plain
#!/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.

 * when a package version it is not released, the topmost entry in the debian/changelog file should contain the string "UNRELEASED" instead of unstable or other valid suite name

{{{
    # 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 DebianBug: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 DebianBug:481806.
See [[Games/VCS/svn]].
Line 287: Line 120:
 * If a package you're working on is for a particular version that has not been uploaded to the archive, you should either append {{{~unrelease0}}} at the end of the version, or use 'UNRELEASED' as the suite in the changelog.  * If a package you're working on is for a particular version that has not been uploaded to the archive, you need to use 'UNRELEASED' as the suite in the changelog.

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 /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.

mr

The mr command can be used to checkout, update, and commit to multiple repositories. In the svn+ssh://svn.debian.org/svn/pkg-games/mrconfig, is a .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 (in Debian Stretch the package is myrepos), 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. Note that the last field on the 'checkout' line ('games' in this instance) should match the last field of the configuration path ('src/packages/games').

[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. The checkout will be approximately 120MB.

Next set up the shared games team .mrconfig. In your ~/.mrconfig, add the following entries.

# Update the games team mrconfig
[src/packages/games-mrconfig]
checkout = svn co svn+ssh://svn.debian.org/svn/pkg-games/mrconfig games-mrconfig
update = svn up ; cp ~/src/packages/games-mrconfig/.mrconfig ~/src/packages/games/.mrconfig

An 'svn up' will pull down two files into the new directory - a README and the .mrconfig file.

Before doing the final checkout (using mr), you need to setup a ~/.mrtrust file. This is supported in all versions of mr from 0.42, and is required for chained checkouts from 1.00 (January 2011). The contents of the file should be a series of paths (one per line) to .mrconfig files. In our case, it will be one line:

/home/YOURNAME/src/packages/games/.mrconfig

Two more "mr checkout" runs (necessary because of bug #447553) will checkout the additional git repositories, into subdirectories of ~/src/packages/games/. (As of December 2011, the full debian-games repo was approx 6.5GB).

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.)

Git

See Games/VCS/git.

SVN

See Games/VCS/svn.

General Rules

  • If a package you're working on is for a particular version that has not been uploaded to the archive, you need to use 'UNRELEASED' as the suite in the changelog.
  • packages/ in the svn repo is for free games only. For games which should go to non-free, please use non-free/package/.
  • the SVN properties of the debian/ directory should point to the location where the orig.tar.gz file(s) can be fetched.

See Also