Contents

  1. Upstream Module Relocations & Re-Naming Guideline
  2. Debian Go Team - Module-Aware Builds Migration FAQ
    1. Case-by-Case Breakdown
      1. CRITICAL: Always Align XS-Go-Import-Path with go.mod
        1. The Issue
      2. Solution
      3. Unvendoring embedded libraries causes go.mod errors
      4. Double-nesting directory structure and misplaced go.mod (e.g. /v2/v2/go.mod)
        1. Symptom
        2. Cause
        3. Solution

Upstream Module Relocations & Re-Naming Guideline

Based on recent mailing list discussions regarding package renames:

1. Import Path Changes: Changing an upstream import path(eg: append major version) requires a new source/binary package, a ITP bug(mention if it's rename for Module-Aware Builds or upstream rename), and DFSG team is already aware during ?DebConf26 that these renamed package will going through the NEW queue very quickly.

2. Git History: When creating new Salsa repositories for renamed modules, please fork/copy git history from the original repository rather than running a fresh dh-make-golang make.

3. Naming Conventions: Convert slashes (/) in Go import paths into hyphens (-) rather than dots (.) when naming packages (e.g., avoid .v3 in favor of -v3), as dots are valid characters for domain name in Go import paths.

4. Verification: Always check https://pkg.go.dev to align the major version with the package name before renaming.

5. Clean Up: Work through all the reverse dependencies package to use new package name. And then file RM to drop the legacy package.

Debian Go Team - Module-Aware Builds Migration FAQ

This page tracks common build issues encountered during the migration to modern, module-aware builds with dh-golang (>= 1.66) and provides the recommended fixes and workarounds.

Based on our previous discussions on mailing list, here is the exact raw content we currently have structured for the MigrationFAQ wiki page.

Case-by-Case Breakdown

CRITICAL: Always Align XS-Go-Import-Path with go.mod

The Issue

Many Phase 1 source uploads are still keeping legacy import paths in debian/control (under the XS-Go-Import-Path field) even though the upstream has been updated to use modern go.mod paths.

This mismatch completely breaks the dependency resolution of the modern dh-golang version 1.66 for reverse dependencies. If the XS-Go-Import-Path does not match the actual Go module import path in go.mod file, go compiler and dh-golang will still fail to locate the dependency during module-aware builds.

Solution

For EVERY package update or transition you perform, you must verify and align XS-Go-Import-Path from go.mod file:

1. Open the upstream go.mod file and identify the declared module path (e.g., github.com/foo/bar/v3 or github.com/foo/bar).

2. Open debian/control and ensure that XS-Go-Import-Path matches this exact path verbatim:

3. If this change introduces a versioned path (like /v3), ensure you also create debian/golang-FOO-dev.links file so we do not break legacy packages. eg: https://salsa.debian.org/go-team/packages/golang-yaml.v2/-/blob/debian/sid/debian/links?ref_type=heads

4. If the links cannot be created for some reason. Build and upload the package into experimental instead. So that this can be useful when we rebuild packages ships executable binaries in phase 2.

Unvendoring embedded libraries causes go.mod errors

Several upstreams include embedded/vendored copies of code from other libraries. This violates Debian Policy, and we generally have tried to remove the vendored copies when packaging the library for Debian. However, with the switch to module-aware builds, the go compiler complains if a downstream consumer's go.mod doesn't include the additional indirect dependency.

First seen with golang-github-klauspost-compress which vendors xxhash, this will likely affect several go libraries currently packaged for Debian.

We should probably have dh-golang dynamically refresh the go.mod file during build by running go mod tidy (or similar). Attempting to patch all consumers to modify their go.mod files won't scale well and will likely require frequent rebasing.

Double-nesting directory structure and misplaced go.mod (e.g. /v2/v2/go.mod)

Symptom

The package builds but results in a completely wrong and duplicated directory layout on the filesystem. The Go files are duplicated under both /v2 and /v2/v2, and the generated go.mod is placed in the wrong nested directory: 

/usr/share/gocode/src/github.com/jcmturner/dnsutils/v2/srv.go
/usr/share/gocode/src/github.com/jcmturner/dnsutils/v2/v2/srv.go
/usr/share/gocode/src/github.com/jcmturner/dnsutils/v2/v2/go.mod

Cause

This is common in legacy .v2 Debian packages packaged around 2020 (the Go 1.13 version), where upstream did not use standard Go module layouts. Instead of a root go.mod, upstream often duplicated their entire codebase into a /v2 directory, placing the go.mod file only inside that subdirectory.

When Debian packaged these, the dh-golang got confused by the versioned suffix (like .v2 or /v2) and duplicated the directory structure, placing the go.mod file at /v2/v2/go.mod.

Furthermore, setting XS-Go-Import-Path to include /v2 (e.g., github.com/jcmturner/dnsutils/v2) is actually incorrect here, as the build system tries to append the version suffix a second time.

Solution

The clean way to resolve this is to correct the target import path metadata and manually patch the source root so that modern dh-golang builds it normally.

1. Fix metadata: Set XS-Go-Import-Path in debian/control to the root import path without the v2 suffix:

2. Add a root go.mod via patch: Since upstream is missing a proper top-level module configuration, write a minimal go.mod file for the root directory, run go mod tidy on it, and include this file as a Debian quilt patch:

3. Clean up debian/rules: Ensure that the helper tools are not instructed to copy or preserve the redundant nested /v2 subdirectory during the install phase.