| 第11章 Packaging with git | ||
|---|---|---|
 |
 |
|
| 第11章 Packaging with git | ||
|---|---|---|
| |
|
|
目次
Up to 「10章上級パッケージング」, we focused on packaging operations without using Git or any other VCS. These traditional packaging operations were based on the tarball released by the upstream as mentioned in 「「Historical perspective」」.
Currently, the git(1) command is the de-facto platform for the VCS tool and is the essential part of both upstream development and Debian packaging activities. (See Debian wiki 「Debian git packaging maintainer branch formats and workflows」 for existing VCS workflows.)
![[注記]](images/note.png) | 注記 |
|---|---|
|
Since the non-native Debian source package uses 「diff -u」 as its backend technology for the maintainer modification, it can’t represent modification involving symlink, file permissions, nor binary data (March 2022 discussion on [email protected]). Please avoid making such maintainer modifications even though these can be recorded in the Git repository. |
Since VCS workflows are complicated topic and there are many practice styles, I only touch on some key points with minimal information, here.
Salsa is the remote Git repository service with associated tools. It offers the collaboration platform for Debian packaging activities using a custom GitLab application instance. See:
There are 2 styles of branch names for the Git repository used for the packaging. See 「「Branch names」」.
There are 2 main usage styles for the Git repository for the packaging. See:
There are 2 notable Debian packaging tools for the Git repository for the packaging.
gbp(1) and its subcommands:
dgit(1) and its subcommands:
It is highly desirable to host Debian source code package on Salsa. Over 90% of all Debian source code packages are hosted on Salsa. [21]
The exact VCS repository hosting an existing Debian source code package can
be identified by a metadata field Vcs-* which can be
viewed with the apt-cache showsrc <package-name>
command.
After signing up for an account on Salsa, make sure that the following pages have the same e-mail address and GPG keys you have configured to be used with Debian, as well as your SSH key:
Salsa runs Salsa CI service as an instance of GitLab CI for 「「Continuous integration」」.
For every 「git push」 instances, tests which mimic tests run on the official Debian package service can be run by setting Salsa CI configuration file 「「debian/salsa-ci.yml file」」 as:
--- include: - https://salsa.debian.org/salsa-ci-team/pipeline/raw/master/recipes/debian.yml # Customizations here
The Git repository for the Debian packaging should have at least 2 branches:
In this tutorial, old style branch names are used in examples for simplicity.
| 注記 |
|---|---|
|
This upstream-branch may need to be created using the tarball released by the upstream independent of the upstream Git repository since it tends to contain automatically generated files. |
The upstream Git repository content can co-exit in the local Git repository used for the Debian packaging by adding its copy. E.g.:
[debhello] $ git remote add upstreamvcs <url-upstream-git-repo> [debhello] $ git fetch upstreamvcs master:upstream-master
This allows easy cherry-picking from the upstream Git repository for bug fixes.
The patch unapplied Git repository can be summarized as:
The source tree matches extracted contents by 「dpkg-source -x --skip-patches」 of the Debian source package.
This repository style is useful for all variants of traditional workflows and gbp based workflow:
「「Patch by 「diff -u」 approach」」
Use helper scripts such as dquilt(1) and gbp-pq(1) to manage data in debian/patches/* files.
Use dput(1) to upload the Debian source package.
The debian/source/local-options and debian/source/local-patch-header files are meant to be recorded by the git command. These aren’t included in the Debian source package.
| 注記 |
|---|---|
|
The focus of this introductory tutorial 「Guide for Debian Maintainers」 isn’t the patch applied Git repository which is rather a new trend. So minimal explanation is given here. |
The patch applied Git repository can be summarized as:
The source tree matches extracted contents by 「dpkg-source -x」 of the Debian source package.
Use one of workflow styles:
dgit-maint-merge(7) workflow.
dgit-maint-debrebase(7) workflow.
The gbp command is provided by the git-buildpackage package.
Use 「gbp import-orig」 to import the new upstream tar to the git repository.
Use 「gbp buildpackage」 to build the Debian binary package from the git repository.
Package history management with the git-buildpackage package is becoming the standard practice for many Debian maintainers. See more at:
The dgit command is provided by the dgit package.
This command is designed to manage contents of 「「Patch applied Git repository」」 efficiently.
The new dgit package offers commands interact with the Debian repository as if it was a git repository. It does not replace gbp-buildpackage and both can be used at the same time. Using plain gbp-buildpackage is recommended for developers who want to run git push/pull on Salsa and use things such as Salsa CI or Merge Requests on Salsa.
For more details see the extensive guides:
The dgit(1) command can push the easy-to-trace change history to the https://browse.dgit.debian.org/ site and can upload Debian package to the Debian repository properly without using dput(1).
Here are some hints.
Topics around dgit are beyond this tutorial document to cover them in depth. Please start reading relevant information:
dgit(1)
For 「「Patch unapplied Git repository」」, you can generate debian/patches/* files using the gbp-pq(1) command from git commits in the through-away patch-queue branch.
Unlike dquilt which offers similar functionality as seen 「「Patch by dquilt approach」」 and 「「Manage patch queue with dquilt」」, gbp-pq doesn’t use .pc/* files to track patch state, but instead gbp-pq utilizes temporary branches in git.
You can add, drop, and refresh debian/patches/* files with gbp-pq to manage patch queue.
If the package is managed in 「「Patch unapplied Git repository」」 using the git-buildpackage package, you can revise the upstream source to fix bug as the maintainer and release a new Debian revision using gbp pq.
Add a new patch recording the upstream source modification on the file buggy_file as:
[debhello] $ git checkout master [debhello] $ gbp pq import gbp:info: ... imported on 'patch-queue/master [debhello] $ vim buggy_file ... [debhello] $ git add buggy_file [debhello] $ git commit [debhello] $ gbp pq export gbp:info: On 'patch-queue/master', switching to 'master' gbp:info: Generating patches from git (master..patch-queue/master) [debhello] $ git add debian/patches/* [debhello] $ dch -i [debhello] $ git commit -a -m "Closes: #<bug_number>" [debhello] $ git tag debian/<version>-<rev>
Drop (== disable) an existing patch
Refresh debian/patches/* files to make 「dpkg-source -b」 work as expected after updating a Debian package to the new upstream release.
[debhello] $ git checkout master [debhello] $ gbp pq --force import # ensure patch-queue/master branch gbp:info: ... imported on 'patch-queue/master [debhello] $ git checkout master [debhello] $ gbp import-orig --pristine-tar --uscan ... gbp:info: Successfully imported version ?.?.? of ../packagename_?.?.?.orig.tar.xz [debhello] $ gbp pq rebase ... resolve conflicts and commit to patch-queue/master branch [debhello] $ gbp pq export gbp:info: On 'patch-queue/master', switching to 'master' gbp:info: Generating patches from git (master..patch-queue/master) [debhello] $ git add debian/patches [debhello] $ git commit -m "Update patches" [debhello] $ dch -v <newversion>-1 [debhello] $ git commit -a -m "release <newversion>-1" [debhello] $ git tag debian/<newversion>-1
For Debian source packages named 「<source-package>」 recorded in the snapshot.debian.org archive, an initial git repository managed in 「「Patch unapplied Git repository」」 with all of the Debian version history can be generated as follows.
[debhello] $ gbp import-dscs --debsnap --pristine-tar <source-package>
The quasi-native packaging scheme packages a source without the real upstream tarball using the non-native package format.
![[ヒント]](images/tip.png) | ヒント |
|---|---|
|
Some people promote this quasi-native packaging scheme even for programs written only for Debian since it helps to ease communication with the downstream distros such as Ubuntu for bug fixes etc. |
This quasi-native packaging scheme involves 2 preparation steps:
Organize its source tree almost like native Debian package (see 「「ネイティブ Debian パッケージ」」) with debian/* files with a few exceptions:
Generate missing upstream tarball preferably without debian/* files.
The rest is the same as the non-native packaging workflow as written in 「「Packaging workflow」」.
Although this can be done in many ways (「「Snapshot upstream tarball」」), you can use the Git repository and 「git deborig」 as:
[~] $ cd /path/to/debhello [debhello] $ dch -r ... set its <version>-<revision>, e.g., 1.0-1 [debhello] $ git tag -s debian/1.0-1 [debhello] $ git rm -rf debian [debhello] $ git tag -s upstream/1.0 [debhello] $ git commit -m upstream/1.0 [debhello] $ git reset --hard HEAD^ [debhello] $ git deborig [debhello] $ sbuild
When your local Git commit history becomes intertwined, you need to organize it before pushing it out to the public.
The most simple organization process is to squash all changes to a single commit using 「git rebase -i」. But this may create a huge illegible commit. Manually splitting the squashed commit using the splitdiff command from the patchutils is an option but may be quite cumbersome.
More fine grained organization process can use 「git rebase -i」 in combination with 「git add some_file」 and 「git commit」. But this may be quite cumbersome.
For this task, the 「git ime」 command in the imediff package can help. It automatically splits a single commit with many files into multiple commits involving only a single file changes. When operating on a single file change commit, it interactively splits the commit into multiple commits of line changes. Invoking it with the --auto* option will automate this commit operation. Now you can manage changes interactively using 「git rebase -i」. By using gitk on the working tree along this task, you get decent visibility over all commits.
| |
|
|
| 第10章 上級パッケージング |
|
第12章 Tips |