Differences between revisions 1 and 9 (spanning 8 versions)
Revision 1 as of 2010-09-08 05:57:49
Size: 3269
Comment:
Revision 9 as of 2018-02-01 09:42:14
Size: 6732
Comment: Add ToC
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:
Still a proposal! == 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: <<TableOfContents>>
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}}}
== Initial setup ==
Line 18: Line 14:
== Repository setup == === Install tools ===
{{{
sudo apt install devscripts debhelper git-buildpackage pristine-tar
}}}
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''. === Set up git URL aliases ===
Line 22: Line 21:
The `debian/` directory lives in the ''debian-<upstream version>'' branch. This branch is created new for every new upstream release and is rebased on the new release. So in practice you go: 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 24: Line 23:
{{
git checkout -b upstream-2.49 upstream-2.48
#import 2.49 here
git add ..
git commit ...
git rebase --onto debian-2.49 upstream-2.49 debian-2.48
git checkout debian-2.49
dch --newversion 2.49-1 --distribution UNRELEASED
}}
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:
}}}
Line 34: Line 33:
Patches and fixes to upstreams are in ''patch-<name>'' or ''typo-<name>'' branches of the respective upstream source. These are not rebased and should be forwarded to upstream. When patches or fixes are no longer needed in the ''master-sid'' branch they are renamed to ''archive-patch-<name>'' or ''archive-typo-name''. 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:
}}}
Line 36: Line 43:
The real package itself is build on the ''master-sid'' branch, which is branched into the ''master-testing'' and ''master-<Debian release codename>'' when the package moves there. === Tell git-buildpackage to use pristine-tar by default ===
Line 38: Line 45:
The ''master-sid'' branch is recreated on each new upstream release like: 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.
Line 40: Line 52:
{{
git branch -m master-sid master-<debian package version>
git checkout -b master-sid debian-<upstream version>
git pull . patch-<name>
git pull . patch-<name 2>
etc
}}
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).
Line 48: Line 54:
If you discover a problem while working on preparing the ''master-sid'' branch you fix is in a new branch, for example if you have a build-failure on sparc due to a GCC bug you can do: == Cloning a repository ==
Line 50: Line 56:
{{
git checkout -b patch-sparc-gcc-bug-in-2.49 upstream-2.49
vi ...
git commit -a -m '...'
git checkout master-sid
git pull . patch-sparc-gcc-bug-in-2.49
}}
Type the following to check out the Debian packaging (here using `sbcl` as an example):
Line 58: Line 58:
Don't forget to forward this new patch to upstream. {{{
gbp clone common-lisp-team:sbcl
}}}
(the `common-lisp-team:` prefix refers to the URL alias set up above)
Line 60: Line 63:
You build using {{git-buildpackage --git-debian-branch=master-sid --git-upstream-branch=upstream-<version> -us -uc}} == Repo layout ==
Line 62: Line 65:
== Other Guidelines == 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.
Line 64: Line 70:
 * Keep the distribution UNRELEASED until we release
 * Keep one commit to one consistent change, use {{{git commit --amend}} in case you make mistakes
 * Do not change `debian/changelog` in the ''patches'' or ''typo'' branches, note the merge explicitly
 * 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.
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.
Line 70: Line 72:
== NMU's and patches == 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 `~`).
Line 72: Line 74:
NMU's are strongly encouraged to apply the changes directly into the git repositories. /!\ 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 "New upstream release."
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.

----
CategoryGit

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 "New upstream release."
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