Packaging guidelines
Cinnamon Team packages are hosted in https://salsa.debian.org/cinnamon-team, Git is the version control system used for packaging.
For help to manage the Git workflow is used gbp (formerly git-buildpackage).
Packages are preconfigured with debian/gbp.conf so the gbp commands don't need extra parameters most of the time.
For managing Debian patches can be used gbp pq (recommended) or Quilt.
The use of gbp pq makes it easy to cherry-pick commits between upstream and downstream Debian.
Policies
Git Branch Names
We use DEP-14 style branch names for new packages, specifically:
debian/latest - The Debianized upstream source directory. In other words, this contains upstream source and a debian/ packaging directory. It is a source-full, patches-unapplied checkout.
pristine-tar - Contains the standard pristine-tar deltas.
upstream/latest - The un-Debianized upstream source. This is what you get when you unpack the upstream tarball. This could also be upstream/<version> if required to manage multiple versions.
Initial packages still use master and upstream branches, will be changed in the future.
gbp pq creates a patch branch, when you want to directly edit upstream source files for export to quilt patches, however this is for local use only and should not be pushed to remote servers.
Git Tag Names
We use '/' as a separator, tags for new Debian version is like debian/6.0.0-1. Can be easily created using gbp tag.
Maintainership
A package maintained within the team should have the name of the team in the Maintainer field.
Maintainer: Debian Cinnamon Team <debian-cinnamon@lists.debian.org>
This enables the team to have an overview of its packages on the DDPO_website.
Some notes
DCT requires a pristine-tar branch, and only upstream tarballs can be used to advance the upstream branch.
Complete upstream Git history should be avoided in the upstream branch. It has been done in the past, but with the packaging also upstream it caused more cons than pros.
Packages must use the UNRELEASED distribution in debian/changelog if the current version in the VCS source has not been uploaded yet. Only when a package's new version is about to be uploaded should the distribution be changed to unstable or another suitable distribution.
Procedures
Checking out a package
If your username differs between your local machine and Salsa, then you can add this snippet to ~/.ssh/config:
Host salsa.debian.org User SALSA_USERNAME
To clone a repository:
$ gbp clone git@salsa.debian.org:cinnamon-team/<srcpkgname>.git
gbp clone is preferable to git clone because gbp clone ensures that you'll have all the remote tracking branches set up properly. You can still use git clone but you'll have to check out the pristine-tar and upstream branches yourself.
You might also want to add this handy little convenience to your ~/.gitconfig file:
[url "git@salsa.debian.org:cinnamon-team/"]
insteadof = dct:which allows you to do this:
$ gbp clone dct:<srcpkgname>.git
Ensure up-to-date before doing anything
Before doing anything on an existing repository, always always always ensure you have pulled in any changes:
$ gbp pull
If you always remember to do this, you reduce the risk of causing accidental git conflicts and reduce risk of waste time.
If you use gbp pq add also --redo-pq to gbp pull
Notes:
if gbp clone was not used and tracking of branches was not setted, manual update of all branches is needed.
the --redo-pq option will discard any local changes to your local patch queue, and replace with the patches from debian/patches.
Building
You can build your package using whatever tools you like, including debuild, dpkg-buildpackage, and git-buildpackage.
New upstream release
![/!\](https://wiki.debian.org/htdocs/debwiki/img/alert.png "/!\"){kind=small}
Before, you should select the correct branch and debian/gbp.conf should already have the correct value debian-branch, otherwise gbp import-orig will merge to the wrong branch. For example if you start working on debian branch different from default make sure is setted correctly with debian-branch in debian/gbp.conf.
If you use gbp pq you should import the patch queue first and after switch again the correct debian branch, or import-orig can do the wrong thing.
$ gbp pq import $ gbp pq switch
Using a debian/watch file (recommended):
$ gbp import-orig --uscan
Using a tarball file:
$ gbp import-orig /path/to/new-upstream.tar.gz
If the upstream tarball is not in the form packagename_version.orig.tar.gz (E.g. package_6.0.0.orig.tar.gz), then the additional -u option is required.
Important notes:
Don't forget to update debian/changelog!
Check if d/patches need refresh or if some applied upstream needs to be removed. In the case you use quilt instead gbp pq you will need more manual operations for this.
- Is useful to check if other packaging changes are needed based on new upstream version changes. Some things may not be visible through only check of build, lintian and possible use of CI-salsa.
Rebase the patches, if you use gbp pq:
$ gbp pq rebase $ gbp pq export
At the end, you will need to push the debian branch, the upstream and pristine-tar branches and the new upstream tag, see Pushing section for details.
Notes for major versions
If new major upstream version changes are only "version bump", bugfixes and/or minor changes that don't require strict depends on other components can be uploaded directly to unstable.
Packages that do not fall into these cases must be uploaded together into experimental first.
They must have strict build-deps, depends and also breaks on previous major version of reverse depends. There can also be a breaks for reverse recommends, for example for cinnamon-l10n.
This help avoids some issues caused by partial upgrade and some days with cinnamon uninstallable in testing if only some packages migrate but one or more is blocked.
Also upstream have packaging, so looking changes to it for new upstream version is useful.
Keep attention that upstream packaging it may not be cared for enough:
- Don't build in clean environment, is possible that don't include all needed build-deps/depends of a package and if other component of the full DE include it don't spot the dependencies lack.
- Don't check for possible policy issue.
- Does packaging for latest Debian stable and Ubuntu LTS, so required changes for new dependencies version support (that there are already in Debian testing/unstable) may be missed. It is possible there are PR done by other distro maintainers related to it and not yet merged.
In Debian packages we try to have good packaging, if there are things missed should be added, if something fixed or improved should be done.
It is recommended to avoid significant differences and conflicts with upstream packaging, when possible, some significant changes may be useful to report upstream and discuss if necessary.
It is good to collaborate with the upstream in order to have better packaging there too and as little different as possible from the Debian one.
For details look here
Pushing
Normally should be pushed the debian branch where did you work, for example debian/latest. When there is new upstream version imported before should be pushed also the upstream/latest (or upstream) and pristine-tar branches and the new upstream tag; more simple and fast way is to use gbp push, if the repository was set up correctly or gbp clone was used and if debian/changelog was updated.
$ gbp push # if new upstream version was imported $ git push origin debian/latest # replace debian/latest with correct branch when different
Tagging
Once you've built and uploaded a new package revision to the Debian repository, you should tag the release.
$ gbp tag
If you want to sign your tag add --sign-tags
The tag must be corresponding to the commit of the upload made and should be pushed only after the upload has been accepted by ftp-master.
Patching
Patching upstream source is done adding patches to debian/patches and is easy. Using gbp pq is a simpler way and recommended. If you want to use quilt instead, look at this page
In general, to patch your package with gbp pq:
1. Creates a patch-queue branch for the selected Debian packaging branch, adding any Debian patches if present.
$ gbp pq import
2. Edit patches that are like normal git commits.
3. When finished, export to return to the packaging branch with updated debian/patches directory.
$ gbp pq export --no-patch-numbers
4. Now you can create the commit with the changes.
5. Optionally, when you have finished working with the patching, to prevent some unexpected events later it might be useful to delete the patch-queue branch, it will be recreated whenever needed.
$ gbp pq drop
Note: don't push patch-queue branches.
Cherry picking upstream commits
Sometimes you need to cherry pick upstream commits, e.g. to fix a bug in the Debian version when upstream hasn't yet released a new version. A convenient way to do that, if upstream is developed in git, is to add a remote and cherry pick from that. For example:
1. Add upstream repo, if not already done. Avoid upstream as name.
$ git remote add upstreamvcs git://example.com/foo.git
2. Fetch upstream repo and create patch-queue if not already done.
$ git fetch upstreamvcs $ gbp pq import
3. Import the upstream commit/s you need.
$ git cherry-pick any_upstream_commit
4. Amend commit for adding Gbp[-Pq] tags, for example Gbp-Pq: Topic upstream to recognize and separate upstream patches, and additional DEP-3 fields in the commit description (if needed).
5. When finished, export to return to the packaging branch with updated debian/patches directory.
$ gbp pq export --no-patch-numbers
Apply patches from file
If need to apply one or more patches related to packaging received as file, for example on bugtracker, you can use git am to quickly apply them including author and commit message.
$ git am 0001-Debian-fix.patch
After, amend the commit done for needed changes, for example adding or fixing the closes tag (Closes: #-1) with the correct number of the bug.
Wrap and sorting
Wrap long lines and sort items in Debian packaging files. Keeping the various lists in alphabetical order can be useful, to save time in various operations. Therefore, it is recommended to perform it regularly. You can also insert new items at the bottom of the list and have them moved in alphabetical order using this command.
$ wrap-and-sort -bst
General documentation
When there is to update Debian policy on package is good to check the Upgrading checklist
dh - debhelper command sequencer
When there is to update debhelper compat of package is good to check the upgrade checklist.