Re: Understanding Git workflow around DEP-14
deb251@lewenberg.com writes:
> Looking at DEP-14 I might have these Git branches:
>
> master
> debian/master
> debian/stretch
> upstream/latest
>
> I understand that the Debian packaging files in debian/ will appear in
> the "debian/*" branch, but my general question is: what is the
> workflow around all these branches? When and how do files get merged
> from one branch to another?
See below for my take on the subject. Don't fear all the complication
spelled out, I'm trying to explain the big picture in the most complex
setting, so things hopefully start to make sense. In practice it's
pretty intuitive once you get the guiding principles.
> 1. Besides the debian/ directory, what is the difference between the
> "debian/master" branch and the "upstream/latest" branch?
Nothing, if you use the "3.0 (quilt)" source format, which you should.
upstream/latest tracks the contents of the pristine upstream tarballs.
If you use pristine-tar, you can reproduce the exact upstream tarballs
from upstream/latest and the appropriate binary deltas (usually stored
in a disconnected/orphan branch called pristine-tar).
> 2. What should the "master" branch be used for?
Whatever your upstream uses it for. As a packager, you use it for
cherry-picking upstream commits into your quilt patch queue and for
creating upstream pull requests by cherry-picking from your patch queue.
In other words: for communicating commits with your upstream. The
"master" branch is not special in a packaging repository, it's just one
of the upstream branches. The default branch of a packaging repository
is usually debian/master. (Some use debian/sid; since uploads from here
can target experimental as well, I prefer debian/master.)
The point of DEP-14 is to work with a clone of the upstream repository,
adding extra branches under the debian/ namespace for packaging for
various Debian distributions, under the ubuntu/ namespace for Ubuntu
distributions and so on, keeping the package vendors separate while
storing upstream tarball contents under the shared upstream/ namespace.
The pristine-tar branch is basically an unordered container of binary
deltas, so it's unique.
> 3. When a new upstream tarball is released, where should it be
> imported? In "upstream/latest"? In "debian/master"? Both?
It's typically imported into upstream/latest, unless you package from
several version series concurrently and thus you have for example an
upstream/2.x branch as well: then you import 2.x tarballs into the
upstream/2.x branch and 3.x tarballs into upstream/latest. You can name
these branches however you please, the point is them being under the
upstream/ namespace for all package vendors' use.
For best effect these import commits should be formal merge commits:
their first parent is the previous import commit, and the second parent
is the upstream commit from which your upstream author created the
release tarball. This is all formal, just a "note of relations" in the
git history; the actual content of the commit is that of the imported
release tarball, not influenced by either parent in any way. However,
these relations are meaningful and git can use them answering queries
like git tag --contains 123456 and similar.
Returning to concrete branch names: in the simplest case your upstream
author tags commits on the master branch and generates tarballs from
them; you then import these tarballs into upstream/latest, formally
merging in the tags on the master branch. However, your upstream may as
well create their release tags on a release branch (say stable2), and
then you import those into upstream/latest all the same, or they can do
both and then you might package both release streams importing into
upstream/2.x and upstream/latest appropriately; DEP-14 is very flexible.
Once the import is done, you fuse it with your packaging work by merging
it into debian/master (assuming a single release stream again). This is
another formal merge: what actually happens is that you replace the
upstream part of the current contents of debian/master with the contents
of upstream/latest, keeping the debian directory (ever present in
debian/master only) unchanged[1]. Then you adjust your packaging files
by committing on debian/master; these commits mustn't touch anything
outside the debian/ directory. You can make upstream changes via files
under debian/patches.
Now, how do you do this all? Simple:
$ gbp import-orig --upstream-vcs-tag=v2.3 ../project-2.3.tgz
Issue the above command on your debian/master branch, where you
committed a debian/gbp.conf file with content like this[2]:
[DEFAULT]
debian-branch = debian/master
upstream-branch = upstream/latest
pristine-tar = True
[import-orig]
merge-mode = replace
Instead of specifying the upstream tarball, you can even use --uscan
most of the time, if you already have a working debian/watch file.
Besides all the git magic described above, this command also creates an
upstream/2.3 tag for future reference.
The usual packaging workflow is you hacking away on debian/master
producing new Debian revisions of the package (gbp buildpackage can
create debian/2.3-1 and similar tags for all your uploads), and
occasionally import new upstream releases by the above procedure. You
upload packages to unstable, they migrate to testing and eventually get
released in stable, for example into buster. You upload further
revisions in the new release cycle, targeting buster, then suddenly a
security issue is uncovered and you have to fix it in buster. This
can't happen through an unstable upload, you might already have a new
upstream release with lots of unrelated changes there. Supposing the
version in buster is 2.3-1, you create the debian/buster branch
starting at the debian/2.3-1 tag. You change the value of debian-branch
in your gbp.conf to debian/buster, and work as usual committing the
security fix and building your package. From this point, you use the
debian/buster branch for buster-security and buster uploads (if you
ever propose stable updates of this package). Similarly, debian/stretch
is used for stretch-security and stretch uploads (while there's still
security support, LTS or oldstable updates for stretch). These branches
stay unrelated, though, you don't usually merge or import new upstream
releases into them, even when you fix the same issue on both.
What if you want to upload backports of your package? Piece of cake:
you create a debian/buster-backports branch starting at the current
testing version of your package (this is typically debian/master).
Change debian-branch in gbp.conf, commit the backporting changes, build
the package, upload. You continue hacking away on debian/master. When
you want to refresh your backport, you merge the new version (typically
debian/master again) into debian/buster-backports, backport the new
changes if needed, build and upload. You can even add another layer for
debian/stretch-backports-sloppy on top of this by branching off from
debian/buster-backports. In principle you could branch off from
debian/master directly as well, but then you don't get the backporting
work already done on debian/buster-backports for free.
[1] With --merge-mode=replace, the new default in git-buildpackage.
[2] For completeness: I usually add these gbp dch and gbp pq settings as
well, look up these very useful tools with man!
[dch]
full = True
multimaint-merge = True
id-length = 7
[pq]
patch-numbers = False
Regards,
--
Feri
Reply to: