DEB-packaging

Introduction
We want to be able to work on DEB packages for OpenStack create working deb packages. This will allow us to work on Ubuntu/Debian compatible packages with community and DEB packages maintainers who are already doing the same work separate.

Goals
The goal of the project is to create and develop further a central place for DEB packages specifications. Here we will maintain Linux packages for the OpenStack. This will allow to involve to development process as maintainers of Linux packages as developers of various types OpenStack projects. Together, we will do better packages.

How to contribute
Select any package from the OpenStack QA page here:

https://qa.debian.org/developer.php?login=openstack-devel@lists.alioth.debian.org

Let's say you want to edit oslo.cache, then simply do:

git clone https://git.openstack.org/openstack/deb-python-oslo.cache

Note the "deb-" prefix above, and the fact that the package name is matching the source package name in the PKG OpenStack QA page. Then you should select the packaging branch. It always will be debian/foo, with foo being the OpenStack release. So for Newton, that will be:

cd deb-python-oslo.cache git checkout debian/newton

Then do a packaging change as usual, then symply do:

git commit -a -m "Some changes" git review

Note that you shouldn't edit debian/changelog. This will be done by the person who will upload to Debian: that person will read the git log since the last packaged new upstream release. Also, after the build is done, you should check that it appears in the infra repository. For example, in here: http://mirror.dfw.rax.openstack.org/debian-openstack/pool/main/p/python-oslo.cache/. If it doesn't, then check the build log (you can us git-os-job to find it). If the build fails because of a hash missmatch fetching from httpredir.debian.org, then simply make a dumb commit (for example, add an empty line in the .gitreview file) to trigger a rebuild, and +2A the CR. In such case, please use the exact title "Dumb commit to rebuild" in the CR. This issue will be fixed when infra will do a proper mirroring of the Debian archive, but until then, we have to deal with these issues.

Releasing a new upstream release package
project-config/gerrit/projects.yaml has the track-upstream option. Meaning that Gerrit should have the latest upstream tag already, and that we should be able to just merge a tag from upstream into the packaging branch. Therefore, here's the procedure. Let's take oslo.cache as an example, and let's make the assumption we want to package the latest version upstream version 1.14.0 for Newton, as per requirements/upper-constrants.txt.

git clone https://git.openstack.org/openstack/deb-python-oslo.cache cd deb-python-oslo.cache git checkout debian/newton git merge -X theirs 1.14.0 dch --newversion 1.14.0-1 -m "New upstream release" git commit -a --amend git review
 * 1) Edit debian/control to fix (build-)dependencies and do any other packaging change needed for the release

Note that the fix of debian/changelog and debian/control should be done in the same single commit as the merge commit, otherwise the package will fail to build.

Once the package builds successfully in OpenStack infra on all the distributions it support (as of writing, this is only Debian Jessie, but we are planning to add more later), then ask a core reviewer to approve your change request. If you are a core reviewer yourself, it's fine to self-approve your change if nobody is around in the #openstack-pkg channel to do it for you.

Once the CR is merged into the OpenStack upstream CI, it is a good moment to also upload it to Debian Experimental.

Note about re-tagging upstream tags:

Some upstream have the bad habit to not use tags which we can use for packaging. For example, some upstream use a "v" as prefix for versions, and Alembic upstream author uses rel_0_8_8 instead of 0.8.8, or Nova may release 14.0.0.0b1, and instead, we need 14.0.0_b1: the packaging scripts transform _ (ie: underscore) into ~ (ie: tilde) so that 14.0.0~b1 is a lower version than 14.0.0. As there's so many tagging scheme, we decided that addressing all of them in scripts was not the solution. Instead, we just re-tag on top of upstream tag. Here's how it looks like for the 14.0.0.0b1 upstream tag of Nova:

git tag -s 14.0.0_b1 14.0.0.0b1 git push gerrit --tags

Note that only the core reviewers can push tags to Gerrit, and that tags MUST be signed, otherwise Gerrit will reject them. Lightweight tags, which would be a nice fit for this case, are unfortunately not an option.

Tagging Debian releases
Only the core packaging-deb group can push tags to gerrit (thanks to the ACL). We also expect that this core group can also upload to Debian. If you want to become core, we strongly suggest that you become the new maintainer process to become at least a DM (ie: Debian Maintainer).

Once the package is uploaded to Debian, you should tag it this way:

git tag -s debian/1.2.3-4 -m "Debian release 1.2.3-4"

Then you can push the tag to gerrit:

git push --tags gerrit

Since the OpenStack CI increment the Debian release versions on each commit (for example, 1.2.3-4+15, if there's 15 commits since 1.2.3-3), then the next change request must edit debian/changelog and increase at least the debian release number, which would then become 1.2.3-5. If that's not done, then the POST job after a merge will not be able to publish the package using reprepro. So dch -i is your friend, and the next packaging change request should look like this:

dch -i -m "some packaging changes" git commit -a -m "some packaging changes" git review

Also, please remember to *never* tag a Gerrit repository if you know that the package will go through the FTP master NEW queue. Otherwise, it may happen that the package is rejected by FTP masters. Then if we need new commits to fix that, they wont be published to the OpenStack infra Debian repository unless we increment the Debian release number, or delete the tag. And none of these 2 is possible or desirable. So please take care when tagging Debian releases!

Contact
The team can be found on the Freenode IRC channel #openstack-pkg. The PTL for the Newton Cycle is Monty Taylor (IRC nick: mordred)