This page is based on DebianMultimedia/DevelopPackaging.
Packages should use git, as mentioned above. Desirable is being able to use git-buildpackage.
Upstream sources should be kept in the upstream branch and the the debian packaging in the master branch.
A patch manager should be used for patch management, and the master branch should only differ from the upstream branch in files inside the debian/ directory. This means no direct changes to the source in the master branch.
The maintainer field should be set to Debian KDE Extras Team <email@example.com>
The git repository should be hosted in alioth, under the pkg-kde project. It should forward commit messages to firstname.lastname@example.org and email@example.com
- You can use the setup-repository script in /git/pkg-kde to create the bare repository with commit messages enabled. The repository should be named as the source package name for the message forwarding to work (eg, the repository for source package liblo is named liblo.git).
- The control file should use the Vcs-Git and Vcs-Browser tags.
One change per commit. This is very important, it eases review, cherry picking, bisecting (and thus debugging) and backporting.
Do not commit debian/changelog along with the changes. This practice makes cherry picking and backporting changes unnecessarily hard. The changelog is generated with git-dch(1) at the time of upload.
The commit message should have a short (<78 characters) summary of the change followed by a newline. After that, you can elaborate on the change. The summary is treated specially by various tools like git-dch(1), or the commitdiff mailer.
- After each upload, the first commit should be creating a new changelog entry, to ease testing of unreleased packages.
- Tags should be created (and signed) by the uploading DD, in the case of the debian tags in the master branch, and by the person importing the upstream sources in the case of upstream tags.
git-buildpackage online documentation (offline: /usr/share/doc/git-buildpackage/manual-html)
Working on existing packages with git for newbies
As a very basic introduction, first read PackagingWithGit.
We generally follow the workflow and defaults of git-buildpackage
locate the packaging branch on the pkg-kde git index
- Note the metadata just above the shortlog, it contains 2 URLs, one of
them starting with git://
then git-clone(1) to get a copy of the repository. E.g.
git clone git://git.debian.org/pkg-multimedia/jack-audio-connection-kit.git
- Do changes to that branch, build the package, test your changes, and commit early and often!
- If someone else has committed while you are working on the branch, you need to integrate his changes. For this you have 2 options:
if your local changes are rather minor and clean, rebase when using git-pull(1):
git pull --rebase origin
- if you rather don't want to break your history because you think that your changes are rather large and are likely to interfere with the other changes, better merge them with:
git pull origin
In case you want to cleanup your local commits before pushing, use git-rebase(1):
git rebase -i origin/master
- You will be presented a textfile where you can specify what of your local commits you want to modify, drop or squish (merge with the previous one). You can also improve your commit message here. Make sure that you don't rewrite already published commits.
In order to get comments on your (preferably cleaned up) commits, use git-format-patch(1) to generate patches of your commits and email them to the mailing list. Any committer can do this while preserving attribution.
- None of the steps above require membership in the pkg-multimedia alioth group. All of that can be done totally anonymously!
Uploading new upstream version to existing repository
- Updating a git branch
$ git checkout master $ git pull
- update local branches without switching to them
$ git remote update $ git fetch alioth upstream:upstream pristine-tar:pristine-tar
- merging a new upstream version
$ git-import-orig --pristine-tar /path/to/<package>_0.0.1.orig.tar.bz
resolve merge conflicts, review your changes e.g. with gitk
- pushing new revisions
$ git push alioth master upstream pristine-tar --tags --dry-run
- if happy, remove the --dry-run parameter
Assumptions in all cases
- in the source tree
- the remote 'alioth' is setup properly