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).

For managing Debian patches can be used gbp pq (recommended) or Quilt.

Policies

Git Branch Names

We use DEP-14 style branch names for new packages, specifically:

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:

Building

You can build your package using whatever tools you like, including debuild, dpkg-buildpackage, and git-buildpackage.

New upstream release

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.

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

{i} 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:

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 upstream tag.

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:

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

TBD

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 upstream_repo git://example.com/foo.git

2. Fetch upstream repo and create patch-queue if not already done.

$ git fetch upstream_repo
$ 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

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

Debian Policy Manual

When there is to update Debian policy on package is good to check the Upgrading checklist

Debhelper tool suite

dh - debhelper command sequencer

When there is to update debhelper compat of package is good to check the upgrade checklist.