Contents
Packaging guidelines
- Packages should use Git, as mentioned above.
Upstream sources should be obtainable via debian/rules get-orig-source
Packages are build from tarballs that upstream provides at http://pub.mate-desktop.org/releases/
The master branch should only contain the debian/ directory.
This means no direct changes to the source can be made in Git. Instead a patch manager (quilt) must be used for patch management.
The maintainer field should be set to MATE Packaging Team <pkg-mate-team@lists.alioth.debian.org>
The Git repository should be hosted on Alioth, under the pkg-mate project. It should forward commit messages to pkg-mate-commits@lists.alioth.debian.org and package_cvs@packages.qa.debian.org
You can use the ./setup-git-repository script in /git/pkg-mate (on host git.debian.org) 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 (e.g. the repository for source package mate-terminal is named mate-terminal.git).
$ ssh -l<alioth-user> git.deban.org $ cd /git/pkg-mate $ ./setup-git-repository <src:package-name>
- The control file should use the Vcs-Git and Vcs-Browser tags.
Workflow guidelines
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.
When releasing a package, the changelog gets created via
$ git dch --auto
This command generates a changelog stanza from the Git commits for the current package version. Thus, choose your Git commit messages well--as if they were entries in debian/changelog. They actually are!!!
Then simply run dch -r which will mark the package from UNRELEASED to released (normally unstable).
Now commit the generated changelog stanza (editing and fine-tuning it is allowed) to Git and (e.g. for Debian release 1.6.1-1 of the mate-common package) use a commit message like
git commit -a -m "upload to unstable (debian/1.6.1-1)"
Build (e.g. with sbuild) and upload the package to Debian unstable.
$ cd <package-dir> $ debuild -uc -us -S -Zxz $ cd .. $ sbuild -sAd unstable <package>.dsc
If you have not used lintian for checking the package integrity, then it is really time for it now:
$ lintian -iIE --pedantic --show-overrides --color auto <package>_<arch>.changes
Only if lintian is considerably silent and content with your package effort, the package is suitable for an upload to Debian unstable. Do not upload a package that lintian still reports errors for.
Now, sign the package (using debsign and (if you are a DD or a DM) upload the package (using e.g. dput):
$ debsign <package>_<arch>.changes $ dput <package>_<arch>.changes
- For uploads to NEW: be patient and wait for the FTP masters to accept the uploaded package... (if they reject it, mark the package as UNRELEASED again and fix what the FTP team requests from you)
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 tag -s debian/1.6.1-1 -m "Debian release 1.6.1-1"
- After each upload, the first commit should be creating a new changelog entry, to ease testing of unreleased packages.
Documentation
Working on existing packages with Git for newbies
As a very basic introduction, first read PackagingWithGit.
locate the packaging branch on the pkg-mate 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-mate/<src:package-name>.git
get the upstream source tarball belonging to that package:
$ debian/rules get-orig-source
do changes to that branch, build the package:
$ debuild -uc -us -Zxz
... and test your changes. Commit early and often! Do regular pushes to the origin Git repos on Alioth.
$ git push origin
- If someone else has committed while you are working on the branch, you need to integrate his/her 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
- only 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
resolve merge conflicts, review your changes e.g. with gitk
- pushing new revisions
$ git push origin master --tags --dry-run
- if happy, remove the --dry-run parameter
Assumptions in all cases
- in the source tree
- the remote 'alioth' is setup properly