|Deletions are marked like this.||Additions are marked like this.|
|Line 139:||Line 139:|
| * If the package hasn't been uploaded yet than debian tag should be deleted. Thus debian tag can be created on upload.
$ git tag -d debian/0.0.1-1
1. Develop Packaging
2. Packages maintained by the Debian Multimedia Team
Here you can find a list of packages maintained by the Debian Multimedia Team:
New packages should set the Maintainer field to Debian Multimedia Maintainers <email@example.com>. Existing packages should move to using that address on a best-effort basis.
All source packages must use the pkg-multimedia in alioth.
3. How to help with packaging
The Debian Multimedia Maintainers need help to create new Debian packages and maintain the existing ones. If you want to contribute to this effort, but you are new to the Debian packaging systems, here follows some information to get you started. Also see DebianMultimedia/Sponsoring for Best Practices with regard to obtaining sponsorship for your uploads if you are not a DD or DM.
3.1. Packaging guidelines
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.
quilt 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.
In order to keep patches uniform, maintainers should configure quilt by means of a ~/.quiltrc file in accordance with the Debian New Maintainers' Guide. Torsten Glaser suggested a more sophisticated ~/.quiltrc file resulting from the team's discussion, the Perl and Maintainer’s Guide suggestions in clean POSIX shell on the pkg-multimedia-maintainers list.
Patches should have a DEP-3 compliant header, and should be submitted upstream (if relevant) before uploading to Debian.
The maintainer field should be set to Debian Multimedia Maintainers <firstname.lastname@example.org>
The git repository should be hosted in alioth, under the pkg-multimedia project. It should forward commit messages to email@example.com and firstname.lastname@example.org
- You can use the setup-repository script in /git/pkg-multimedia 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.
3.2. 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. Also, packages should use the changelog release heuristic of dch(1).
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 to the Debian FTP servers, 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.
- To indicate that the package is ready for upload, update debian/changelog to include the target distribution (i.e. 'unstable' or 'experimental'). Otherwise just leave 'UNRELEASED'. If you want a review or help, just ask on this mailing list.
git-buildpackage online documentation (offline: /usr/share/doc/git-buildpackage/manual-html)
3.4. Proposing new packages for pkg-multimedia
If you are confident with your package, propose it for review on the pkg-multimedia-maintainers mailing list. Link to your package preferably in a way that can be easily used with ?dget. The debian mentors site is a good place.
- Members of the team will then review your package and give you hints how to improve it. If the package is "good enough" (at the reviewer's discretion), he will setup a repository on git.debian.org and integrate your package while preserving attribution.
3.5. 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
As an optimization, you can heavily speed up git by setting this:
git config --global 'url.git://git.debian.org.insteadOf' 'git+ssh://git.debian.org' git config --global 'url.git+ssh://git.debian.org.pushInsteadOf' 'git+ssh://git.debian.org'
- This allows non-team members to pull from alioth without requiring ssh access.
locate the packaging branch on http://git.debian.org. All pkg-multimedia branches have pkg-multimedia in their url. Click on the leftmost link in that line. That will bring you to the summary of the project.
- Note the metadata just above the shortlog, it contains 2 URLs, one of
them starting with git+ssh://
then gbp-clone(1) to get a copy of the repository. E.g.
$ gbp clone --pristine-tar git+ssh://git.debian.org/git/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!
4. Common tasks for team members
4.1. Uploading proposed package to the team git repository
- First create a repository on git.debian.org:
$ ssh git.debian.org /git/pkg-multimedia/setup-repository <project>
- Then import the sources locally, register the remote archive and push your commits (i.e. upload changes) with the following commands:
$ cd /path/to/sources/ $ gbp import-dsc --pristine-tar <project>_0.0.1-1.dsc $ cd <project> $ git remote add origin git+ssh://email@example.com/git/pkg-multimedia/<project>.git $ git push origin master upstream pristine-tar --tags
- If the package hasn't been uploaded yet than debian tag should be deleted. Thus debian tag can be created on upload.
$ git tag -d debian/0.0.1-1
4.2. Uploading new upstream version to existing repository
Updating a git branch:
$ git checkout master $ git pull
or by running:
$ gbp pull
update local branches without switching to them:
$ git remote update $ git fetch origin upstream:upstream pristine-tar:pristine-tar
merging a new upstream version:
$ gbp import-orig --pristine-tar /path/to/<package>_0.0.1.orig.tar.bz
resolve merge conflicts, review your changes e.g. with gitk:
$ git commit
pushing new revisions:
$ git push origin master upstream pristine-tar --tags --dry-run
- if happy, remove the --dry-run parameter
Assumptions in all cases
- in the source tree
- the remote 'origin' is setup properly
4.3. Removing/Adding debian tags to repository
Removing debian tag:
$ git tag -d debian/0.0.1-1
Adding debian tag:
$ git-buildpackage --git-tag-only
Alternatively, it's possible to create tags by hand:
$ git tag [-a|-s] "debian/0.0.1-1" -m "Debian release 0.0.1-1"
-s (or -u <key>) for GPG-signed tag
- -a for unsigned tag
$ git push origin master --tags
Replacing a previously set tag:
$ git tag -f [-a|-s] "debian/1.2.3-1" -m "Debian release 1.2.3-1"
4.4. Common configuration options
These parameters should be placed in the debian/gbp.conf file. (uncomment compression line if upstream tarball(s) are not gzip-compressed)
[DEFAULT] pristine-tar = True #compression = bzip2
If you adopt the dpkg source format 3.0 (quilt) you should:
* Add this to debian/source/format file
* Add this to .gitignore file
* Add this to debian/source/local-options file
4.5. Bugs for packages found in DMO
If there is a bug that is not found in the Debian version of a package but found only in the DMO version of the package, it is helpful to mark such bugs with a usertag. The procudure we take to mark such bugs is as follows.
Send an email to close the bug (NNNNNfirstname.lastname@example.org) and also to the BTS bug control interface (email@example.com). Closing the bug will automatically notify the submitter of the bug as well. The contents of the email must begin with the following lines.
user firstname.lastname@example.org usertags NNNNNN dmo tags NNNNNN = unreproducible notfound NNNNNN <version1> notfound NNNNNN <version2> ... notfixed NNNNNN <version1> notfixed NNNNNN <version2> ... stop
These lines are read by the BTS bug control interface. The 'user' line must be set to 'email@example.com' so that the usertag can be set. The 'usertags' marks the bug with the usertag 'dmo'. The 'tags' line will reset all tags on the bug so that it will only contain one tag, the 'unreproducible' tag. The 'notfound' lines removes all instances where the BTS says the bug is found. These lines need to be added for each version the BTS says the bug is found against. In case the BTS says there are versions of the package the bug is fixed, the 'notfixed' lines must also be added just like the 'notfound' lines to unmark all versions where the BTS says the bug is fixed. Finally, the 'stop' line stops processing for the BTS control interface.
After the 'stop' line, write a message explaining that this bug does not exist against the version of the package in Debian and is being close and marked as such. It's also helpful to recommend users to report the bug to dmo.
All such marked bugs can be viewed at http://bugs.debian.org/cgi-bin/pkgreport.cgi?tag=dmo;firstname.lastname@example.org.
Work in progress : We're checking all the WNPP bugs and updating infos on this page.