Repositories

Give me the source!
SSH tips
Git repository
Common Git branches
Other Git branches
Tags for upstream and package releases
Upstream Git repositories
Subversion repository
Migration of a source package from Subversion to Git

We use Git and Subversion (SVN) repositories, hosted by Debian. You can have a look at each repository through Alioths web interfaces: cgit and ViewVC.

The Git repository is the primary location for our source packages these days. However, the Subversion repository is still used for some packages that have not migrated to Git yet.

Warning

For most direct operations on the repositories in Alioth, an umask of 002 is necessary to avoid problems of missing write permission to the other team members.

Give me the source!

To check the sources of a package (referred as <package> below) in our repositories, use the debcheckout command, from the devscripts package.

  • If you are a member of Debian GIS or a Debian Developer, with account name <username>, you have write permission to our VCS repositories:

    • If the package is already in the archive:

      debcheckout --user <username> --git-track '*' <package>
      

    • For draft packages that are only on Alioth:

      debcheckout --user <username> git://git.debian.org/pkg-grass/<package>.git --git-track '*'
      debcheckout --user <username> svn://svn.debian.org/pkg-grass/packages/<package>/trunk <package>
      

  • For read-only access, remove the --user option:

    debcheckout --git-track '*' <package>
    

    You can configure Git to use SSH only for push actions, by changing the URL:

    git remote set-url --push origin ssh://<username>@git.debian.org/git/pkg-grass/<package>.git
    

SSH tips

You can avoid specifying your Alioth user name by setting it in ~/.ssh/config as follows. Note that in that case, with debcheckout you can replace the --user option by the -a option, for less typing.

Host *.debian.org
	User your-user-name

You can avoid typing your SSH password again and again using the ssh-add command. On remote connections the SSH agent needs to be enabled with the command eval $(ssh-agent).

In case of trouble getting SSH working it is a good idea to read the Alioth/SSH wiki article.

Git repository

The area on Alioth that contains the Git repositories (/git/pkg-grass) uses as flat hierarchy for packages and related Debian GIS repositories.

There is no mandated layout for the package repositories, the following layout is recommended though.

pkg-grass/
 ├ <package-A>.git
 │  ├ master
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ pristine-tar
 │  └ upstream
 ├ <package-B>.git
 │  ├ master
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ wheezy
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ ubuntu/quantal
 │  │  ├ <upstream sources>
 │  │  └ debian/
 │  ├ pristine-tar
 │  └ upstream
 ┆
 └ website.git
    └ master

Common Git branches

Most of our packages using Git and stored in Alioth are managed following the standard layout of the git-buildpackage helper.

  • The master branch contains the full source package.

    Upstream sources are merged with Debian-specific changes in the master branch, which is the usual place to work in.

  • The pristine-tar branch contains the data necessary to recreate an original tarball from the repository with a reproducible checksum.

    The data needed to regenerate original source tarballs from the upstream branch are kept with the help of the pristine-tar tool in the pristine-tar branch.

  • The upstream branch contains the upstream source, after repacking when necessary (non-free files, large convenience code copies, …).

    Upstream sources are kept (in plain, uncompressed form) in the upstream branch.

git-buildpackage can be set to a directory layout similar to the one we use with svn-buildpackage by using the export-dir and tarball-dir options. However those settings should only be in a system-wide or user-wide gbp.conf file and not the one committed in the Git repository.

Other Git branches

Changes uploaded to other distributions than Debian unstable can be stored in other branches, named for instance experimental, jessie, etc.

This is useful in case updates to packages in Debian stable are made and the master branch already uses a newer upstream release. Using dedicated branches for the older version in Debian named after the release codename is recommended.

Packaging for the UbuntuGIS PPA is encouraged to be stored in Ubuntu release specific branches such as ubuntu/trusty, ubuntu/xenial, etc.

Likewise packaging for other derivatives can be maintained in the Debian GIS git repository in derivative specific branches. OSGeo-Live for example can use branches such as osgeo/9.5, osgeo/10.0, etc.

Using UbuntuGIS and derivative release specific branches assist collaboration between Debian GIS and the UbuntuGIS and derivative teams. Changes from Debian or Ubuntu can be merged or cherry picked from their respective branches without needing to obtain the source packages to manually merge the changes from.

Tags for upstream and package releases

The tagging convention used for upstream and package releases follows the defaults of git-buildpackage.

  • upstream/<upstreamversion> for upstream releases, e.g. upstream/1.2.0

  • debian/<debianversion> for Debian releases, e.g. debian/1.2.0-1

Tags for package releases targeting derivative distributions use a distribution specific prefix followed by the package version separated by a / character:

<distribution>/<package_version>

Examples of the tagging convention for known derivatives:

  • ubuntu/<debian_version>~<ubuntu_codename><revision_number> for UbuntuGIS backports based on the Debian GIS packaging, e.g. ubuntu/1.2.0-1~trusty1

  • osgeo/<debian_version>~<ubuntu_codename><revision_number> for OSGeo-Live releases and backports based on the Debian GIS packaging, e.g. osgeo/1.2.0-1~xenial1

Upstream Git repositories

For some projects, like the ones hosted on GitHub or GitLab, it may be easier to forward changes made in the Debian package if this one is itself mirrored on the same platform, as a clone. In that case, the layouts may vary from package to package, and the branch that contains the Debian work will probably not be the master one. If it is not the default branch, it must be indicated in the VCS URL with the -b option.

Even when you are not using git-buildpackage, please include a debian/gbp.conf, to document the layout of the repository.

When working with upstream Git repositories, it's convenient to have the upstream repository configured as a Git remote called upstream. Fetching the upstream commit history into the package repository allows among others per commit reviews of new upstream releases, and reading extended commit messages.

When the upstream Git repository is not configured as a remote in the Debian GIS Git repository on Alioth, you may not want to push the upstream tags, because the referenced commits only exist in the upstream Git repository.

Subversion repository

The SVN repository is structured as follows:

pkg-grass/
 ├ cvs2svn/
 │  ├ branches/
 │  └ tags/
 ├ packages/
 │  ├ <package A>/
 │  │  ├ branches/
 │  │  ├ tags/
 │  │  └ trunk/
 │  │     └ debian/
 │  ├ <package B>/
 │  │  ├ branches/
 │  │  ├ tags/
 │  │  └ trunk/
 │  │     └ debian/
 │  …
 └ scripts/

Migration of a source package from Subversion to Git

For packages where we set the mergeWithUpstream property, which excludes the upstream sources, there is no easy way to prepare a Git repository from our Subversion repository that would look like the package was always managed in Git. Nevertheless, the following recipe will generate a Git repository that contains all the history of the debian directory, plus a collection of selected upstream source releases.

  • Start the conversion as explained in the Alioth/Git page of the Debian wiki. To be consistent with a later usage of git-buildpackage, it is preferable to prefix the tag names debian. During this conversion, you can take advantage of the file /trunk/community/infrastructure/comitters in the Subversion repository, and expand it if necessary.

  • Import of the upstream original tarballs that you find relevant, for instance the ones that were part of a stable release). When this paragraph was written, it was necessary to follow special instruction detailed in bug #471560.

  • Upload to git.debian.org/git/pkg-grass and set up the hooks and other meta-data as explained in the Alioth/Git page of the Debian wiki.

  • Document in the Subversion repository that the package has been transferred elsewhere, for instance with a file named README.status containing the new VCS URL.

  • Delete the package in the Subversion repository after its VCS URL in stable has been updated by the next release.

It is also possible to prepare a Git repository containing some of the package's history using the command gbp import-dscs --debsnap from the helper toolkit git-buildpackage. This will download all the versions of a package available in snapshot.debian.org and create tags for each of them. Note that as this paragraph is written, the tool is not aware that backports should be a different branch.