Re: RFC: DEP-14: Recommended layout for Git packaging repositories
On Thu, 13 Nov 2014, Bernhard R. Link wrote:
> * Raphael Hertzog <hertzog@debian.org> [141111 22:26]:
> > Helper tools should usually rely on the output of `dpkg-vendor --query vendor`
> > to find out the name of the current vendor. The retrieved string must be
> > converted to lower case. This allows users to override the current vendor
> > by setting `DEB_VENDOR` in their environment (provided that the vendor
> > information does exist in `/etc/dpkg/origins/`).
>
> Is using the vendor you use git on a good default for the vendor code
> you are currently working on? In my experience those two are quite
> unrelated.
Do you have a better default to suggest? In any case, having a default
value is certainly better than not having one and forcing everybody to
configure it in some ways.
I try to work in Kali chroots when I do Kali work. It's true that
it's not always the case but if there were real differences right now I
would pay more attention or would ensure to have the proper environment.
> > Version mangling
> > ----------------
> >
> > When a Git tag needs to refer to a specific version of a Debian package,
> > the Debian version needs to be mangled to cope with Git's restrictions.
> > The colon (`:`) needs to be replaced with a percent (`%`), and the tilde
> > (`~`) needs to be replaced with an underscore (`_`).
>
> Is there a previous case of encoding colons with percent signs?
This is the current convention used by git-buildpackage and I believe the
"%" has been picked because it's visually close to ":" (i.e. two dots/two
circles).
> If it is inventing a third way instead of using on of the existing ones,
> is sounds like a bad idea.
Do you suggest to use URL encoding? That's rather heavyweight for two
special cases that can be easily mapped to other characters that are not
used in version strings. And it would convert characters that do not
need any special escaping currently.
1:1.2.3+dfsg-4~3 gives:
suggested scheme: 1%1.2.3+dfsg-4_3
full url encoded: 1%3A1.2.3%2Bdfsg-4%7E3
Or what else do you have in mind?
> > Packaging branches and tags
> > ===========================
> >
> > The Git repository listed in debian/control's `Vcs-Git` field should
> > usually have its HEAD point to the branch corresponding to the
> > distribution where new upstream versions are usually sent. For Debian,
> > it will usually be `debian/sid` (or sometimes `debian/experimental`).
>
> I think this should alternatively allow for Vcs pointing to that branch
> instead. It sometimes makes sense to put the debian package development
> branches in the same repository as the upstream branch, where HEAD might
> be reserved for the upstream branch.
Right, fixed by making it conditional on the absence of "-b branch":
-NOTE: The Git repository listed in debian/control's `Vcs-Git` field should
+NOTE: If the Git repository listed in debian/control's `Vcs-Git` field does
+not indicate an explicib branch (with the `-b <branch>` suffix) then it should
have its HEAD point to the branch where new upstream versions are being
> > When releasing a Debian package, the packager should create and push
> > a signed tag named `<vendor>/<version>`.
>
> I'd advocate s/signed/(possibly signed)/, as I'm not ready to sign such
> a wildcard with any valuable key and getting another very-low-security
> key just to have signed keys to match this proposal sounds like waste.
Changed to "(preferably signed)".
> Tags are only based on versions are also quite hard to shuffle around.
> I'd strongly suggest adding the name of the source package to those,
> otherwise accessing multiple packages in on repository causes a big
> mess. (git keeps branches in the per-origin "remote" namespace when
> fetching stuff, tags only have one global namespace, local and remote).
I don't think this makes sense. The common case is a single software per
git repository. If you have multiple software, then the git way is
to use git submodules. If you have an upstream that doesn't follow those
conventions, then it's a good reason to not follow DEP-14 for the tagging
of your Debian releases.
But I don't think that DEP-14 should cater to upstreams are are going
against the spirit of traditional git usage.
Maybe we can document this as a special case where it's a good idea to
not follow DEP-14 ?
I added this:
@@ -255,6 +257,19 @@ of the `debian/changelog` file are handled by `dpkg-mergechangelogs` as
this will make it much easier to merge between different packaging
branches.
+When to not follow the above recommendations
+--------------------------------------------
+
+Most of the recommendations in this document assume that the upstream
+developers use their Git repository in a traditional way: one software per
+repository and creating tags for released versions.
+
+When the upstream diverge from those conventions, you are entitled
+to use your common sense and adapt those recommendations accordingly.
+For example, if upstream tags contain the software name (e.g.
+`foo-1.0` and `bar-2.0`), you should probably also consider embedding
+the name in the tags used for your package releases.
+
Changes
=======
> > Importing upstream releases from Git tags
> > -----------------------------------------
> >
> > When the packaging branches are directly based on the upstream Git
> > branches, upstream usually also provide proper Git tags that can be reused
> > for official releases.
> >
> > If helper tools have to identify the upstream commit corresponding to a
> > given upstream release, they should be able to find it out by looking up
> > the following Git tags: `upstream/<version>`, `<version>` and
> > `v<version>`.
> >
> > The `upstream/<version>` tag would be created by the package maintainer
> > when needed: for example when it does a release based on a Git snapshot or
> > when the tag naming scheme used by upstream is not following the above
> > rules.
>
> That lacks possibility three: importing tar content on top of upstream
> branches.
This is a combination of both, and I'm not convinced it is worth to be
explicity mentionned. Do other persons feel differently ?
> > Native packages
> > ===============
> >
> > The above conventions mainly cater to the case of non-native packages,
> > that is when the upstream developers and the package maintainers are
> > not the same set of persons.
> >
> > When upstream is Debian (or one of its derivative), the upstream vendor
> > should not use the usual `<vendor>/` prefix (but all others vendors should
> > do so). The main development branch can be named `master` instead of
> > the codename of the target distribution (although you are free to still
> > use the codename if you wish so).
>
> Does native here mean a native package or a package developed primarily
> for Debian (which can also use a non-native packaging)? This paragraph
> seems to mix those two concepts quite a bit.
Yes it mentions both concepts. I tried to word it in a way that is clear
enough though. If you find some parts ambiguous, let me know which one
or suggest a better wording.
I tried to improve this:
@@ -175,9 +177,8 @@ a byte-for-byte copy of the upstream tarballs, this should be done in the
Native packages
===============
-The above conventions mainly cater to the case of non-native packages,
-that is when the upstream developers and the package maintainers are
-not the same set of persons.
+The above conventions mainly cater to the case where the upstream
+developers and the package maintainers are not the same set of persons.
When upstream is Debian (or one of its derivative), the upstream vendor
should not use the usual `<vendor>/` prefix (but all others vendors should
@@ -185,11 +186,12 @@ do so). The main development branch can be named `master` instead of
the codename of the target distribution (although you are free to still
use the codename if you wish so).
-When the package is shipped as a native source package, the concept of
-"upstream sources" is irrelevant and the associated `upstream/*` branches
-are irrelevant too. Note that even if the upstream vendor ships the
-package as a native package, the downstream vendors can still can opt to
-package it in a non-native way.
+When the package is shipped as a native source package (i.e. a single
+tarball with no differentiation of the upstream sources and of the
+packaging files), the concept of "upstream sources" is irrelevant and the
+associated `upstream/*` branches are irrelevant too. Note that even if the
+upstream vendor ships the package as a native package, the downstream
+vendors can still can opt to package it in a non-native way.
Patch queue tags
================
> > A patch queue branch is a (temporary) branch used to define the set
> > of upstream changes that the package will contain, its content is
> > generally used to later update `debian/patches` in the resulting
> > source package.
>
> s/(temporary)/(possibly temporary)/ ?
Ack.
> > What to store in the Git repository
> > -----------------------------------
> >
> > It is recommended that the packaging branches contain both the upstream
> > sources and the Debian packaging. Users who have cloned the repository
> > should be able to run `dpkg-buildpackage -b -us -uc` without doing
> > anything else (assuming they have the required build dependencies).
>
> ++
> (except that one of course needs to get the .orig.tar.gz using
> pristine-tar or uscan for a non-native package needs to be an exception
> from "anything else")
This is not required for "dpkg-buildpackage -b" but only for "dpkg-buildpackage -S".
> > Managing debian/changelog
> > -------------------------
> >
> > This DEP makes no specific recommendation on how to manage the Debian
> > changelog. Some maintainers like to use tools like `gbp dch` to generate
> > the changelog based on Git commit notices, others edit the file manually
> > and use tools like `debcommit` to reuse the changelog entry in the
> > Git commit.
> >
> > Helper tools should however configure the Git repository so that merges
> > of the `debian/changelog` file are handled by `dpkg-mergechangelogs` as
> > this will make it much easier to merge between different packaging
> > branches.
>
> Ugh. Please do not encourage tools to pester with my git config.
> (Perhaps this want meant as something to do when automatically creating
> a repository for you?)
Yes, I meant it mainly for things like "gbp clone".
Cheers,
--
Raphaël Hertzog ◈ Debian Developer
Support Debian LTS: http://www.freexian.com/services/debian-lts.html
Learn to master Debian: http://debian-handbook.info/get/
Reply to: