Re: Major version suffix for new packages
On Sun, Oct 5, 2025 at 3:30 AM Richard Hansen <rhansen@rhansen.org> wrote:
>
> I'm new to the Debian Go team and am seeking some advice.
>
> What is the preferred way to handle major version suffixes (e.g., /v2)
> when creating a package for a library module that has not been packaged
> yet? There are multiple parts to this:
>
> * The value of the XS-Go-Import-Path field in debian/control.
> * The location of the installed source files in /usr/share/gocode/src.
> * The naming convention for the source and binary packages.
>
> The subdirectory of /usr/share/gocode/src that dh-golang installs to
> seems to always match the XS-Go-Import-Path field, which is good.
>
> dh-make-golang usually omits the /vN subdirectory from
> XS-Go-Import-Path. (An example of where it *does* include the /vN
> subdirectory is `dh-make-golang make -allow_unknown_hoster
> zgo.at/zcache/v2`.) This is problematic: One module I attempted to
> package (I wish I remembered which one) failed a unit test because
> <https://pkg.go.dev/runtime#Func.Name> returned the wrong value (no /vN
> suffix). The discussion at
> <https://lists.debian.org/debian-go/2020/06/msg00003.html> suggests that
> Go magically does the right thing if go.mod is installed along with the
> source code, even if the code is not installed to a /vN subdirectory.
> Unfortunately, dh-golang doesn't appear to install go.mod by default.
> Even if it did, the lack of /vN subdirectory means that:
>
> * two different major versions of the same library cannot be
> installed simultaneously, and
> * comparing a module's name to XS-Go-Import-Path is not reliable.
>
> Because of this, I think it makes the most sense to include the /vN
> suffix, despite the default behavior of dh-make-golang.
>
> Regarding the Debian package naming convention, the archive currently
> contains a mix of the following patterns:
>
> 1. Source golang-*, binary golang-*-dev
> Example: golang-github-coreos-go-oidc
>
> This seems to be the most common. If rigorously followed,
> only one major version of a module could exist in the
> archive at a time. dh-make-golang seems to use this most
> of the time (but not always; see #5 below).
>
> 2. Source golang-*-dev, binary golang-*-dev
> Example: golang-github-masterminds-semver-dev
>
> This seems like a mistake. Only 7 packages are like this.
>
> 3. Source golang-*, binary golang-*-vN-dev
> Example: golang-github-jackc-chunkreader
>
> Only 2 packages are like this. This style implies that a
> single source package would produce multiple different
> major version binary packages, which seems awkward to me.
>
> 4. Source golang-*, binary golang-*.vN-dev
> Example: golang-github-go-macaron-macaron
>
> This is a variant of #3 (dot vN instead of dash vN). Only
> one package uses this pattern.
>
> 5. Source golang-*-vN, binary golang-*-vN-dev
> Example: golang-github-hashicorp-golang-lru-v2
>
> This is the most general/flexible (along with pattern #6).
> The downside is it's a hassle to upload an entirely new
> package (and eventually remove the old package) whenever
> the major version is bumped. dh-make-golang uses pattern
> #5 for invocations like:
>
> dh-make-golang make -allow_unknown_hoster zgo.at/zcache/v2
>
> 6. Source golang-*.vN, binary golang-*.vN-dev
> Example: golang-github-pion-ice.v2
>
> This is a variant of pattern #5 (dot vN instead of dash vN),
> and seems to be more popular than pattern #5. The lack of
> consistency bothers me -- why is '/' translated to '-'
> everywhere except when the last component of the module name
> is "/vN"?
>
> My preference is #5 (with #6 in second place), but I'm not yet familiar
> enough with the Debian Go team's tooling and packaging practices to be
> fully aware of the consequences.
>
Thanks for raising this.
First I want to point out that the dot vN pattern is misled by the
gopkg.in project before Go modules.
Before Go modules, gopkg.in introduced dot vN pattern in Go package
name. It's part of the package name, not the version.
Some people misused it in v2+ Go modules. We should fix that.
Other options all have pros and cons. With vN in package/source name,
we can package multi versions together. W/o vN in name, we can move
more quickly as changing name needs to go through NEW queue and
removing old versions needs more manpower.
This is not a unique question for Go libraries. Other languages also
have. Just looking at these C libraries which have versions in the
-dev header library name. I don't think we have a documented rule for
the C language. Probably the common sense is to put the version in the
source/binary package name, when the transition to a new version is
hard.
--
Shengjing Zhu
Reply to: