The golang-github-cenkalti-backoff transition is in progress. One thing
that I found about this is that some packages uses the following in the
*.go source code files:
import (
...
"github.com/cenkalti/backoff"
with go.mod saying something like:
github.com/cenkalti/backoff v2.1.1+incompatible
or they don't have a go.mod at all, and some packages uses
import (
...
"github.com/cenkalti/backoff/v4"
with go.mod saying:
require (
github.com/cenkalti/backoff/v4 v4.3.0
The former packages needs patching to pick up the right /v4 namespace,
whereas the latter just needs B-D/D to say
golang-github-cenkalti-backoff-v4-dev instead of
golang-github-cenkalti-backoff-dev.
This is a curiosity and for future reference, I suspect we'll have other
similar transitions.
I wonder if there is something in upstream Go libraries that lead to
packaging using versioned vs unversioned import statements. Is there
any Go ecosystem guidlines on what to use? Or is this per package,
depending on what the particular Go library recommends as its namespace?
/Simon
Simon Josefsson <simon@josefsson.org> writes:
> However 'dh-make-golang make' never sets that up, nor have I seen this
> in any common use? We have plenty of v2, v3, v4, v5 etc in the archive
> and very few seems to have XS-Go-Import-Path including the /vX part.
>
> For example of a popcon heavy v5 package that doesn't use that approach:
> https://salsa.debian.org/go-team/packages/golang-github-containers-image/-/blob/debian/sid/debian/control?ref_type=heads#L59
>
> I guess I never understand the semantics of XS-Go-Import-Path. The Go
> team documentation doesn't really mention it at all except for this
> quote:
>
> You will need to change the value of XS-Go-Import-Path in
> debian/control to correspond to your program’s upstream package
> name. This is usually what you would go get when installing it
> manually. dh-golang needs that information so that it can run go
> install.
>
> If I understand how most Go packages work, the /vX is not part of the
> "upstream package name" which I presume is the same as used in import
> statements, although I'm not familiar with this terminology.
>
> I think we can use /v4 for the *-v4-dev package, but doesn't need to
> touch this for the normal (future v5) *-dev package.
>
> /Simon
>
> Reinhard Tartler <siretart@gmail.com> writes:
>
>> Hi Simon,
>>
>> Yes, you are correct. My understanding is that the api version component at
>> the end of the XS-Go-Import-Path field should only be omitted for V1 (the
>> versionless default). Later versions of the API, such as v4 and v5, should
>> be placed in their respective subdirectories (/v4/, /v5/) for the golang
>> module path lookup to work as expected.
>>
>> At least that's my current understanding of the situation.
>>
>> regards,
>> Reinhard
>>
>> On Wed, Dec 10, 2025, 08:20 Simon Josefsson <simon@josefsson.org> wrote:
>>
>>> Reinhard Tartler <siretart@gmail.com> writes:
>>>
>>> > Hi Simon,
>>> >
>>> > Regarding the file conflict issue, how about having the
>>> > golang-github-cenkalti-backoff-v4-dev files installed under a
>>> subdirectory
>>> > like /usr/share/gocode/src/github.com/cenkalti/backoff/v4/
>>>
>>> Yes, that is how the package work:
>>>
>>>
>>> https://ftp-master.debian.org/new/golang-github-cenkalti-backoff-v4_4.3.0-2.html
>>>
>>> My question was more if 'XS-Go-Import-Path:
>>> github.com/cenkalti/backoff/v4' is the right way to achieve that, or has
>>> that header some other semantics that I'm unaware of?
>>>
>>> > and the existing v5 files installed under /usr/share/gocode/src/
>>> > github.com/cenkalti/backoff/v5/?
>>>
>>> Do we need that? Can't the normal golang-github-cenkalti-backoff-dev
>>> package be a normal packaging of that project, using regular
>>> 'dh-make-golang make' defaults?
>>>
>>> If the *-v4-dev package puts the file into v4/ there is no conflict with
>>> v5 files in ../.
>>>
>>> > While this approach might still cause breakage in some packages that
>>> expect
>>> > a simple, versionless import path, I expect it would require less overall
>>> > patching across all of Debian and keeps the package structure closer to
>>> how
>>> > Go upstream handles versioned imports.
>>>
>>> The only breakage with the above scheme is in packages that are stuck on
>>> v4, which may need a patch to use our v4 namespace. But that is
>>> expected, and as Otto analyzed, we can hopefully migrate most of those
>>> packages to v5 once we have both in unstable.
>>>
>>> Actually we can migrate them to v5 by putting new upstream uploads into
>>> experimental now. I prefer to get the *-v4-dev package into unstable
>>> first, and then upgrade all of the reverse dependencies from *-dev to
>>> *-v4-dev without bumping upstream version first though. But we can do
>>> anything in experimental while unstable is undisturbed.
>>>
>>> /Simon
>>>
>>> > Best regards,
>>> >
>>> > Reinhard
>>> >
>>> > regards,
>>> > Reinhard
>>> >
>>> > On Wed, Dec 10, 2025, 03:08 Simon Josefsson <simon@josefsson.org> wrote:
>>> >
>>> >> I've uploaded to NEW:
>>> >>
>>> >>
>>> https://salsa.debian.org/go-team/packages/golang-github-cenkalti-backoff-v4
>>> >>
>>> >>
>>> https://salsa.debian.org/jas/golang-github-cenkalti-backoff-v4/-/pipelines/988017
>>> >>
>>> >> Review appreciated! I think everything except naming can be resolved
>>> >> after it passes NEW review.
>>> >>
>>> >> Is 'XS-Go-Import-Path: github.com/cenkalti/backoff/v4' the right thing?
>>> >> I'm not sure if that is the best way to add the /v4/ file-name suffix.
>>> >> Something to avoid filename Conflicts will probably be needed, but it
>>> >> could be done in other ways too.
>>> >>
>>> >> /Simon
>>> >>
>>>
>
Attachment:
signature.asc
Description: PGP signature