Hi Simon, Toddy, (cc' Nilesh) On Fri, Jul 17, 2026 at 8:49 AM Simon Josefsson <[email protected]> wrote: > > Andrew Lee <[email protected]> writes: > > > I update the MigrationFAQ page and added `CRITICAL: Always Align > > XS-Go-Import-Path with go.mod`. > > https://wiki.debian.org/Teams/DebianGoTeam/MigrationFAQ > > Thanks! I didn't understand this.
Thank you for point this out Simon. I beleve you are not the only one who has this questions in mind. I will explain how the dependencies resolving works under `module-aware builds` in more details below. (Toddy: Please correct if I am wrong) > Can we get a lintian check for this added ASAP? I pass this to Nilesh with my explaination below. > One thing I still don't understand: XS-Go-Import-Path should only be > identical to the TOP-LEVEL go.mod module path, right? > If a project has a foo/bar/baz/go.mod, then that module path should not > be put into XS-Go-Import-Path, right? > When it is appropriate to have multiple paths in XS-Go-Import-Path? > That's used sometimes. Can we use this to add both the previous and new > value? > What if a project does not have a top-level go.mod but several go.mod in > sub-directories? Maybe this is not common. Maybe synthesize a > XS-Go-Import-Path with a value above the go.mod module paths in > sub-directories? If I ever find a project like that, I'll bring it up. All of these questions has the an answer once we understand how this `module-aware builds` works in Go compiler with our new dh-golang 1.66. Under modern `module-aware builds`, resolving Go modules dependency is much simpler based on Go compiler itself. The Go compiler finds dependencies using the module import path from go.mod file. During a Debian `offline build`, dh-golang acts as a local replacer to map these import paths from internet(replace GOPROXY) to physical directories on the filesystem under /usr/share/gocode/src/. To make this mapping to works, the directory structure shipped in -dev package must match the path expected by go compiler with go.mod file as well. After understoodd how go compiler resolves with new dh-golang 1.66, helps us to understand how to handle the -dev packaging: * No more multiple XS-Go-Import-Path: We no longer need to list multiple paths in XS-Go-Import-Path. The XS-Go-Import-Path should only declare a single TOP-level of the modern module path. Unless some special case that GOPROXY handles the legacy rename mappings(eg: yaml package). And for us, the legacy path compatibility is handled purely on the filesystem using symlinks. * Subdirectory modules: If a project doesn't have a root go.mod and only contains modules nested in subdirectories, XS-Go-Import-Path still shouldn't point to those submodules. It always remains the single root identifier for the entire source tree. So that we should still point XS-Go-Import-Path to the TOP-level of the modern module path. I hope this helps everyone in this transition phases. Please feel free to let me know if I missed any of your questions or you have additional questions? :) Happy hacking, -- -Andrew
