Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cmd/go: document version tagging for modules not at the repo root #36014

Closed
Minnozz opened this issue Dec 6, 2019 · 5 comments
Closed

cmd/go: document version tagging for modules not at the repo root #36014

Minnozz opened this issue Dec 6, 2019 · 5 comments
Labels
Documentation FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@Minnozz
Copy link

Minnozz commented Dec 6, 2019

What version of Go are you using (go version)?

$ go version
go version go1.13.4 linux/amd64

Does this issue reproduce with the latest release?

I have not tried any newer point releases, but the code from master contains the unexpected behaviour.

What did you do?

  • I have a git repository, example.org/maindir, which contains a subdirectory subdir, with a go.mod file.
  • The git repository has two tags:
    • v0.1.0, which was created when go.mod was in the main directory.
    • v0.2.0, which was created when go.mod was in the subdirectory.
  • I ran go get example.org/maindir/subdir in a different modules-enabled project to add it a as a dependency.

What did you expect to see?

I expected the algorithm to choose version v0.2.0 for example.org/maindir/subdir.

What did you see instead?

The algorithm chose v0.0.0-20191206111401-2e6237601202 as the version.

I did some digging, and apparently, when the go.mod file is not located in the repository root, the code that selects versions to consider filters out all tags that do not start with the path from the repo root. In this example, that means that the expected format of the tags for modules in a repository subdir is subdir/v0.2.0. As far as I know, this is undocumented behaviour.

Relevant snippet here:

go/src/cmd/go/internal/modfetch/coderepo.go

Lines 141 to 144 in 0915a19

p := prefix
if r.codeDir != "" {
p = r.codeDir + "/" + p
}

The only reference to this behaviour I could find in the documentation is in this FAQ item: https://github.com/golang/go/wiki/Modules#is-it-possible-to-add-a-module-to-a-multi-module-repository

There, the line git tag mig/v1.0.0 gave me the idea that this might be the issue, but it is not explained anywhere.
@Minnozz
Copy link
Author

Minnozz commented Dec 6, 2019

I would say there are two points:

  • Is this behaviour valid? As far as I know, this naming scheme for semver tags for subdirectories is not common practice.
  • If it is valid, this behaviour should be documented more clearly.

@cagedmantis cagedmantis changed the title Version selection algorithm expects undocumented subdir/v1.2.3 tag format when go.mod is not in the repository root cmd/go: version selection algorithm expects undocumented subdir/v1.2.3 tag format when go.mod is not in the repository root Dec 6, 2019
@Minnozz
Copy link
Author

Minnozz commented Dec 7, 2019

Another suggestion: when there are 0 tags in the subdir/v1.2.3 format, the algorithm might want to consider tags in the regular v1.2.3 format before resorting to choosing v0.0.0-20191206111401-2e6237601202-style tags.

@jayconrod
Copy link
Contributor

Is this behaviour valid? As far as I know, this naming scheme for semver tags for subdirectories is not common practice.

This is valid. Modules within a repository are versioned independently. That means there needs to be a namespace of tags for each module. We accomplish that with a subdir/ prefix.

If it is valid, this behaviour should be documented more clearly.

Agreed. I'm working on module reference documentation for 1.14 (#33637), which will include that. It will be linked from https://golang.org/doc. I expect that will supercede a lot of information in go help and on the wiki.

I don't expect everyone will immediately reach for reference documentation though, since it will be long and verbose. Where would you look for this information? Would a blog post or similar article help?

Another suggestion: when there are 0 tags in the subdir/v1.2.3 format, the algorithm might want to consider tags in the regular v1.2.3 format before resorting to choosing v0.0.0-20191206111401-2e6237601202-style tags.

Unfortunately, we can't mix those namespaces. Version tags should be permanent. If version tags are added for the root module later, they can't change the meaning for versions of non-root modules.

@jayconrod jayconrod added this to the Unreleased milestone Dec 9, 2019
@Minnozz
Copy link
Author

Minnozz commented Dec 9, 2019 •
edited

Where would you look for this information? Would a blog post or similar article help?

Yes, a blog post or article would definitely help. When researching this issue, I ended op on the Multi-Module Repositories section of FAQ. I see now that I missed this line on my initial read:

The tag for version 1.2.3 of module "my-repo/foo/rop" is "foo/rop/v1.2.3".

So the information is there, but it's quite easy to miss.

Also, I'm not sure if this is possible, but it might be nice if go get -v example.org/maindir/subdir would warn when there are 0 tags in the subdir/v1.2.3 format, but 1 or more tags in the v1.2.3 format. go get -v is the first command I tried to get more information about why the tags were not considered.

@toothrot toothrot added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Dec 9, 2019
@bcmills bcmills changed the title cmd/go: version selection algorithm expects undocumented subdir/v1.2.3 tag format when go.mod is not in the repository root cmd/go: document version tagging for modules not at the repo root Feb 26, 2020
@bcmills bcmills modified the milestones: Unreleased, Backlog Feb 26, 2020
@seankhliao
Copy link
Member

This is now on https://go.dev/ref/mod#vcs-version , which go refers to for full documentation

@golang golang locked and limited conversation to collaborators Jun 7, 2023
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
Documentation FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
Backlog
Development

No branches or pull requests
6 participants
@toothrot @jayconrod @Minnozz @bcmills @gopherbot @seankhliao