Differences between revisions 5 and 6
Revision 5 as of 2012-07-25 18:19:28
Size: 2134
Editor: ThomasKoch
Comment:
Revision 6 as of 2018-01-29 17:54:10
Size: 6679
Comment: Overhaul of git packaging workflow for Common Lisp Team
Deletions are marked like this. Additions are marked like this.
Line 2: Line 2:
= Git usage in the Common Lisp packaging Team =
Line 4: Line 3:
In use for clisp. == Overview ==
The Debian Common Lisp Team uses `git-buildpackage` to make working with the packaging repositories easier.
Line 6: Line 6:
Recommandations for handling the [[http://en.wikipedia.org/wiki/Git_%28software%29|Git]] repository. The [[#Repo layout|package layout]] is the default `git-buildpackage` layout with full upstream source, upstream tarballs (no upstream git history) and `pristine-tar`.
Line 8: Line 8:
== Useful links == The git repositories can be browsed at: https://salsa.debian.org/common-lisp-team
Line 10: Line 10:
The Git repositories are stored on Alioth, for example for clisp we have: == Initial setup ==
Line 12: Line 12:
 * [[http://git.debian.org/?p=pkg-common-lisp/clisp.git;a=summary|web view]]
 * For people with Alioth access: {{{git clone ssh://git.debian.org/git/pkg-common-lisp/clisp.git}}}
 * Anonymous access either one of:
  * {{{git clone http://git.debian.org/git/pkg-common-lisp/clisp.git}}}
  * {{{git clone git://git.debian.org/git/pkg-common-lisp/clisp.git}}}
=== Install tools ===
{{{
sudo apt install devscripts debhelper git-buildpackage pristine-tar
}}}
Line 18: Line 17:
== Repository setup == === Set up git URL aliases ===
Line 20: Line 19:
Upstream goes to a branch called ''upstream'', each upstream version that is packages is also a branch ''upstream-<version>''. The upstream for a released Debian version has a parallel branch called ''upstream-<Debian code name>'', for example ''upstream-lenny''. Git has a feature to rewrite URLs. We can use this to create handy shortcuts that require less characters to type and will make migration easier if your username ever changes (for instance, if you become a Debian Developer and no longer need a -guest account) or if the repo ever moves.
Line 22: Line 21:
The `debian/` directory lives in the ''debian-<debian version>'' branch. This branch is created new for every new upstream release and is rebased on the new release. So in practice you go: You can set up and change git url handling in your `~/.gitconfig` or `~/.config/git/config`
{{{
[url "git@salsa.debian.org:common-lisp-team/"]
        insteadof = common-lisp-team:
}}}
or you can achieve the same with `git config`:
{{{
git config --global url.git@salsa.debian.org:common-lisp-team/.insteadof common-lisp-team:
}}}

If you do not have write permissions yet, you will need to use the anonymous url:
{{{
[url "https://salsa.debian.org/common-lisp-team/"]
        insteadof = common-lisp-team:
}}}
or
{{{
git config --global url.https://salsa.debian.org/common-lisp-team/.insteadof common-lisp-team:
}}}

=== Tell git-buildpackage to use pristine-tar by default ===

The following should be put in your `~/.gbp.conf`:
{{{
[DEFAULT]
pristine-tar = True
}}}
so that all git-buildpackage commands use the `pristine-tar` branch by default.

If you need to override this for a given repository (that does not have the `pristine-tar` branch), you can use the `--git-no-pristine-tar` or `--no-pristine-tar` option (depending on the command).

== Cloning a repository ==

Type the following to check out the Debian packaging (here using `sbcl` as an example):
Line 25: Line 57:
git checkout -b upstream-2.49 upstream-2.48
#import 2.49 here
git add ..
git commit ...
git rebase --onto debian-2.49-1 upstream-2.49 debian-2.48-3
git checkout debian-2.49-1
dch --newversion 2.49-1 --distribution UNRELEASED
gbp clone common-lisp-team:sbcl
}}}
(the `common-lisp-team:` prefix refers to the URL alias set up above)

== Repo layout ==

The Debian Common Lisp Team uses the current default git-buildpackage layout for its repositories.

The primary packaging branch is named `master`. The parallel branch for upstream source without the `debian/` directory is named `upstream`.

The `pristine-tar` branch is used for storing information necessary to recreate a bit-to-bit identical tarball.

The latest version of the package should always be committed to the `master` branch. Per-release branches, using the distribution codenames (e.g. `stretch` or `jessie`), can be used for (old)stable uploads if the need arises.

For each upstream and Debian version, a corresponding tag is created, with the respective patterns `upstream/${UPSTREAM_VERSION}` and `debian/${DEBIAN_VERSION}` (standard git-buildpackage mangling rules apply for some special characters like `:` or `~`).

/!\ Some repositories may have branches or tags that do not follow this naming pattern. This is most likely because another git workflow was used in the past, before standardizing on the one described on this page.

== Building the package ==

This can be achieved using:
{{{
gbp buildpackage
Line 34: Line 82:
Patches and fixes to upstreams are in quilt and live also in the debian-<version> branches. Several useful options are:
 * `--git-ignore-new`: for building even if there are uncommitted changes
 * `--git-pbuilder`: to build with `git-pbuilder`
 * `--git-builder`: to build with another builder such as `sbuild`
 * `--git-tag`: to create the `debian/${DEBIAN_VERSION}` tag at the end of the build process
 * `--git-debian-branch=$BRANCH`: for building a branch different from `master`
Line 36: Line 89:
You build using {{{git-buildpackage --git-debian-branch=debian-<debian version> --git-upstream-branch=upstream-<version> -us -uc}}} Moreover, all options not prefixed with `--git` are passed to the builder (which by default is `debuild`), so you can directly pass options such as `-S` (for source-only).
Line 38: Line 91:
== Other Guidelines == == Updating the repository ==
Line 40: Line 93:
 * Keep the distribution UNRELEASED until we release
 * Keep one commit to one consistent change, use {{{git commit --amend}}} in case you make mistakes
 * After each upload, the first commit should be creating a new changelog entry with distribution set to UNRELEASED
 * If upstream uses a SVC consider importing the upstream changes into the git tree.
Pulling remote changes into your remote copy can be achieved with:
{{{
gbp pull
}}}
Line 45: Line 98:
== NMU's and patches == This will update all three default branches (`master`, `upstream`, `pristine-tar`) and tags.
Line 47: Line 100:
NMU's are strongly encouraged to apply the changes directly into the git repositories. == Making a change ==

Edit the corresponding files, modify the changelog, stage all your changes (with `git add`) and finally create the commit (using `debcommit`).

Please keep the `debian/changelog` series as `UNRELEASED` until the version is actually being uploaded.

== Importing a new upstream version ==

Assuming that `debian/watch` contains the right information, this can be achieved using:
{{{
gbp import-orig --uscan
}}}
This will download the tarball, update the `upstream` and `pristine-tar` branches, create the `upstream/${UPSTREAM_VERSION}` tag, and merge `upstream` into `master`.

Then you should create a new changelog entry:
{{{
dch -v ${UPSTREAM_VERSION}-1
git add debian/changelog
debcommit
}}}

== Pushing your changes ==

With the version of git-buildpackage in buster/unstable:
{{{
gbp push
}}}
(this will push all three default branches and all tags)

With the version of git-buildpackage in stretch and older:
{{{
git push --all
git push --tags
}}}

== Making a Debian release ==

Here we finalize the changelog, build the source package (for a source-only upload) and create the release tag, and push the latest packaging and release tag.
{{{
dch -r
git add debian/changelog
debcommit -r
gbp buildpackage -S --git-tag
gbp push
}}}

Then sign and upload the `_source.changes` file.

If you want to do a source+binary upload (typically for a NEW upload), or use another builder, you should adapt the `gbp buildpackage` line (keeping the `--git-tag` option).


== Vcs-* fields ==

The Vcs fields in `debian/control` should be the following:
{{{
Vcs-Browser: https://salsa.debian.org/common-lisp-team/${PACKAGE}
Vcs-Git: https://salsa.debian.org/common-lisp-team/${PACKAGE}.git
}}}

== Commit notifications by email ==

When creating a new repository on Salsa, please setup the commit notifications by email through tracker.debian.org, see [[Salsa/Doc#Email_notifications]].

This can be easily achieved with the scripts from https://salsa.debian.org/mehdi/salsa-scripts, using:
{{{
./emails_on_push.sh common-lisp-team/${PACKAGE} dispatch+${PACKAGE}_vcs@tracker.debian.org
}}}

== Further documentation ==

=== Using git ===
A full git tutorial is beyond the scope of this wiki page. See the [[https://git-scm.com/book/|Pro Git book]] for one popular guide.

=== Using git-buildpackage ===
Please read the [[https://honk.sigxcpu.org/projects/git-buildpackage/manual-html/|manual]] to learn how to use git-buildpackage.

Overview

The Debian Common Lisp Team uses git-buildpackage to make working with the packaging repositories easier.

The package layout is the default git-buildpackage layout with full upstream source, upstream tarballs (no upstream git history) and pristine-tar.

The git repositories can be browsed at: https://salsa.debian.org/common-lisp-team

Initial setup

Install tools

sudo apt install devscripts debhelper git-buildpackage pristine-tar

Set up git URL aliases

Git has a feature to rewrite URLs. We can use this to create handy shortcuts that require less characters to type and will make migration easier if your username ever changes (for instance, if you become a Debian Developer and no longer need a -guest account) or if the repo ever moves.

You can set up and change git url handling in your ~/.gitconfig or ~/.config/git/config

[url "git@salsa.debian.org:common-lisp-team/"]
        insteadof = common-lisp-team:

or you can achieve the same with git config:

git config --global url.git@salsa.debian.org:common-lisp-team/.insteadof common-lisp-team:

If you do not have write permissions yet, you will need to use the anonymous url:

[url "https://salsa.debian.org/common-lisp-team/"]
        insteadof = common-lisp-team:

or

git config --global url.https://salsa.debian.org/common-lisp-team/.insteadof common-lisp-team:

Tell git-buildpackage to use pristine-tar by default

The following should be put in your ~/.gbp.conf:

[DEFAULT]
pristine-tar = True

so that all git-buildpackage commands use the pristine-tar branch by default.

If you need to override this for a given repository (that does not have the pristine-tar branch), you can use the --git-no-pristine-tar or --no-pristine-tar option (depending on the command).

Cloning a repository

Type the following to check out the Debian packaging (here using sbcl as an example):

gbp clone common-lisp-team:sbcl

(the common-lisp-team: prefix refers to the URL alias set up above)

Repo layout

The Debian Common Lisp Team uses the current default git-buildpackage layout for its repositories.

The primary packaging branch is named master. The parallel branch for upstream source without the debian/ directory is named upstream.

The pristine-tar branch is used for storing information necessary to recreate a bit-to-bit identical tarball.

The latest version of the package should always be committed to the master branch. Per-release branches, using the distribution codenames (e.g. stretch or jessie), can be used for (old)stable uploads if the need arises.

For each upstream and Debian version, a corresponding tag is created, with the respective patterns upstream/${UPSTREAM_VERSION} and debian/${DEBIAN_VERSION} (standard git-buildpackage mangling rules apply for some special characters like : or ~).

/!\ Some repositories may have branches or tags that do not follow this naming pattern. This is most likely because another git workflow was used in the past, before standardizing on the one described on this page.

Building the package

This can be achieved using:

gbp buildpackage

Several useful options are:

  • --git-ignore-new: for building even if there are uncommitted changes

  • --git-pbuilder: to build with git-pbuilder

  • --git-builder: to build with another builder such as sbuild

  • --git-tag: to create the debian/${DEBIAN_VERSION} tag at the end of the build process

  • --git-debian-branch=$BRANCH: for building a branch different from master

Moreover, all options not prefixed with --git are passed to the builder (which by default is debuild), so you can directly pass options such as -S (for source-only).

Updating the repository

Pulling remote changes into your remote copy can be achieved with:

gbp pull

This will update all three default branches (master, upstream, pristine-tar) and tags.

Making a change

Edit the corresponding files, modify the changelog, stage all your changes (with git add) and finally create the commit (using debcommit).

Please keep the debian/changelog series as UNRELEASED until the version is actually being uploaded.

Importing a new upstream version

Assuming that debian/watch contains the right information, this can be achieved using:

gbp import-orig --uscan

This will download the tarball, update the upstream and pristine-tar branches, create the upstream/${UPSTREAM_VERSION} tag, and merge upstream into master.

Then you should create a new changelog entry:

dch -v ${UPSTREAM_VERSION}-1
git add debian/changelog
debcommit

Pushing your changes

With the version of git-buildpackage in buster/unstable:

gbp push

(this will push all three default branches and all tags)

With the version of git-buildpackage in stretch and older:

git push --all
git push --tags

Making a Debian release

Here we finalize the changelog, build the source package (for a source-only upload) and create the release tag, and push the latest packaging and release tag.

dch -r
git add debian/changelog
debcommit -r
gbp buildpackage -S --git-tag
gbp push

Then sign and upload the _source.changes file.

If you want to do a source+binary upload (typically for a NEW upload), or use another builder, you should adapt the gbp buildpackage line (keeping the --git-tag option).

Vcs-* fields

The Vcs fields in debian/control should be the following:

Vcs-Browser: https://salsa.debian.org/common-lisp-team/${PACKAGE}
Vcs-Git: https://salsa.debian.org/common-lisp-team/${PACKAGE}.git

Commit notifications by email

When creating a new repository on Salsa, please setup the commit notifications by email through tracker.debian.org, see Salsa/Doc#Email_notifications.

This can be easily achieved with the scripts from https://salsa.debian.org/mehdi/salsa-scripts, using:

./emails_on_push.sh common-lisp-team/${PACKAGE} dispatch+${PACKAGE}_vcs@tracker.debian.org

Further documentation

Using git

A full git tutorial is beyond the scope of this wiki page. See the Pro Git book for one popular guide.

Using git-buildpackage

Please read the manual to learn how to use git-buildpackage.


CategoryGit