Differences between revisions 9 and 93 (spanning 84 versions)
Revision 9 as of 2008-05-17 06:00:58
Size: 7595
Editor: ?AndresMejia
Comment: Add note on how to import orig tarball when converting from svn
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 1: Line 1:
== Git ==
The repositories for the packaging in git is stored in a different manner than they are under svn. Each package has its own git repository (and thus its own directory) under the /git/pkg-games directory on the alioth servers.
#language en
<<TableOfContents>>
Line 4: Line 4:
This guide assumes that you are uploading the packaging files for a package for the first time. 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.
Line 6: Line 6:
A separate section will describe how to import the packaging that was stored in the svn repository in the future. == Scheme ==
Line 8: Line 8:
=== Environment variables ===
These are some environment variables that git uses when you commit changes. It's best to set these environment variables so that git doesn't rely on your system's username or hostname. Place this snippet in your ~/.bashrc configuration file.
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.
 . http://alioth.debian.org/account/register.php

The next step is to join the team. Visit the Alioth page for the team and click on "request to join".
 . https://alioth.debian.org/projects/pkg-games/ [[https://alioth.debian.org/project/request.php?group_id=30862|direct link]]

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.
Line 11: Line 19:
# Git variables
export GIT_AUTHOR_NAME='<your name>'
export GIT_AUTHOR_EMAIL='<your email>'
export GIT_COMMITTER_NAME='<your name>'
export GIT_COMMITTER_EMAIL='<your email>'
$ ssh-keygen
Line 18: Line 22:
=== Creating a git repository ===
First, create a repository in the /git/pkg-games directory on the alioth servers.
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.
 . https://alioth.debian.org/account/editsshkeys.php

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.
Line 21: Line 27:
$ mkdir <package>.git
$ cd <package>.git
$ git --bare init --shared
$ cat >>~/.ssh/config <<EOF
Host svn.debian.org
        User <username>

Host git.debian.org
        User <username>

Host alioth.debian.org
        User <username>
EOF
Line 26: Line 39:
Now edit the 'description' file in the directory you just created to one that is appropriate for the package. Now you should be able to logon from each of your machines by doing the following.
Line 28: Line 41:
$ echo "Packaging for <package>" >description $ ssh svn.debian.org
$ ssh git.debian.org
$ ssh alioth.debian.org
Line 30: Line 45:

Let's also enable the use of 'hooks/post-update'.
{{{
$ chmod a+x hooks/post-update
}}}

Now we're done creating a repository for the package. You could also use the 'setup-repository' script that's in the pkg-games directory. That script is really a symlink to the script that's used in the collab-maint directory.
{{{
./setup-repository <package> '<package description>'
}}}

Please see the documentation about mr below, and add the new repository to list of games team repositories in the .mrconfig file.

=== Uploading a package to the repository ===
Now let's import the package into a git repository. This is easy using 'git-import-dsc' from the 'git-buildpackage' package.
{{{
$ git-import-dsc --pristine-tar <package>.dsc
}}}

(The --pristine-tar option is optional; if you have pristine-tar installed this will store enough information in the git repository to reproduce the pristine upstream tarball later.)

A directory with the name of the source package should have been made. Change into that directory.
{{{
$ cd <package>
}}}

Ensure the tags that are created reflect if a package has been released. git-buildpackage creates tags for the debian branch and the upstream branch. If the tag created for the debian branch reflects an unreleased version, you'll have to delete that "debian" tag.
{{{
$ git-tag -l
$ git-tag -d 'debian/<unreleased version>'
}}}

Finally, push the repository up to the repository on alioth.
{{{
$ git-remote add alioth git+ssh://<username>@git.debian.org/git/pkg-games/<package>.git
$ git-push alioth master
$ git-push alioth upstream
$ git-push alioth pristine-tar
$ git-push alioth --tags
}}}

(Again the pristine-tar step is optional.)

=== Accessing a repository ===
To get a repository, do the following.
{{{
$ git-clone git+ssh://<username>@git.debian.org/git/pkg-games/<package>.git
}}}

You can also enjoy read-only access by using the following.
{{{
$ git-clone git://git.debian.org/git/pkg-games/<package>.git
$ git-clone http://git.debian.org/git/pkg-games/<package>.git
}}}

To view a summary of the repository on your favorite web browser, go to the following address.
{{{
http://git.debian.org/?p=pkg-games/<package>.git
}}}

=== Committing changes ===
To commit a change, first commit into your local repository.
{{{
$ git-commit -m "<some comment>"
}}}

You could also do a commit of all files that were changed using the '-a' option.
{{{
$ git-commit -a -m "<some comment>"
}}}

Push your changes.
{{{
$ git-push #If you cloned the repository
$ git-push alioth #If you created the repository using the above example
}}}

=== Updating ===
To keep updated simply do the following
{{{
$ git-pull #If you cloned the repository
$ git-pull alioth #If you created the repository using the above exmple
}}}

=== Tagging ===
To tag a release, you could build it using 'git-buildpackage' with the '--git-tag' option.
{{{
$ git-buildpackage --git-tag --pristine-tar
}}}

(As usual, the --pristine-tar bit is optional, but it will allow git-buildpackage to extract the pristine .orig.tar.gz.)

You could also manually tag the package. Ensure that you are in the correct branch (should be 'master').
{{{
$ git-checkout master
$ git-tag debian/<revision> -m "Debian release <revision>" #Please use this format
}}}

To tag an earlier revision, you'll need to find out it's commit object, then tag that object.
{{{
$ git-rev-list --pretty --since="1 month" --all #'1 month' is just an example of course
$ git-tag debian/<revision> <commit object> -m "Debian release <revision>"
}}}

Finally, push the tags
{{{
$ git-push --tags
}}}

=== Converting from svn repository ===
To convert from the svn repository, first setup the git repository on the alioth servers as described above. Afterwards, do the following.
{{{
$ mkdir <package>
$ cd <package>
$ git-svn init --no-metadata \
    --trunk svn://svn.debian.org/svn/pkg-games/packages/trunk/<package> \
    --branches svn://svn.debian.org/svn/pkg-games/packages/branches/<package> \
    --tags svn://svn.debian.org/svn/pkg-games/packages/tags/<package>
$ git-svn fetch
}}}
Note: Doing {{{git-svn fetch}}} will take some time depending on how many commits were done in the svn repository.

After fetching from the svn repository, it's now time to import the contents of the orig source.
## Thanks to Stefano Zacchiroli <zack@debian.org> for reporting this at http://bugs.debian.org/471560.
{{{
$ git-symbolic-ref HEAD refs/heads/upstream
$ git-rm --cached -r .
$ git-commit --alow-empty -m 'initial upstream branch'
$ git-checkout -f master
$ git-merge upstream
$ git-import-orig <path_to_tarball>
}}}
Note: There's usually a one hour delay when uploading your ssh public keys. During this delay, you can still login with your password.
Line 165: 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 169: 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 177: 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 179: 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 185: Line 87:
{{{
Line 186: Line 89:
}}}
Line 189: Line 93:
{{{
Line 190: Line 95:
}}}
Line 193: Line 99:
{{{
Line 194: Line 101:
}}}
Line 197: Line 105:
{{{
Line 198: Line 107:
}}}
Line 201: Line 111:
=== See Also ===
 * [:Alioth/Git]
 * http://www.kernel.org/pub/software/scm/git/docs/
== 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 ==
 * [[Alioth/Git]]
 * http://www.kernel.org/pub/software/scm/git/docs/ - git Documentation
 * [[SmallSVNTutorial]]
 * [[Alioth/Svn]]
 * http://svnbook.red-bean.com/ - Subversion Documentation
 * [[http://www.hmug.org/man/5/ssh_config.php|ssh_config man page]] - Manual on OpenSSH SSH client configuration files
 * [[http://git.or.cz/gitwiki/GitCheatSheet]] - Git Cheat

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