cmd/go: stamp the pseudo-version in builds generated by go build

[4ad]

cmd/go embeds dependency version information in binaries, which is very useful. From Go 1.18 onwards, cmd/go also embeds VCS information in binaries, which makes it even more useful than it was before.

As #37475 mentions, people place version information in binaries using -ldflags='-X foo=bar', which requires an additional build wrapper. The new VCS stamping feature of cmd/go should alleviate the need for external wrapper, but I am afraid it comes short.

The version information, in the sense of Go's pseudo version is not recorded for the main module when doing go build:

: emerald:ver; go build
: emerald:ver; go version -m hello | grep 'mod.*hello'
	mod	mgk.ro/hello	(devel)	
: emerald:ver; 

The version is recorded as expected when doing go install:

: emerald:ver; go install robpike.io/ivy@latest
go: downloading robpike.io/ivy v0.1.124
: emerald:ver; go version -m `which ivy` | grep 'mod.*ivy'
	mod	robpike.io/ivy	v0.1.12	h1:qI7dnEiXhorB+za07W6qX3sG+IvBK4EUl38vUHAf53Q=
: emerald:ver; 
: emerald:ver; 

I am afraid this limitation of cmd/go will continue to force people to use external build wrappers that set -ldflags, which is rather unfortunate.

I am not the first to want main module version information in binaries, this has been already asked for in various issues, for example in #29814, which was closed as a duplicate of #37475, but it really wasn't a duplicate, as #37475 is about VCS information, and #29814 is about semantic versioning. Other examples of people asking for this feature are mvdan/sh#519 and #29228 (comment) where various workarounds were proposed.

Speaking of workarounds, the only workaround that I know that currently works would be to create a local module proxy and pass GOPROXY to go install, but that is an extremely high-overhead workaround, and go install is not a replacement for go build anyway, since go install comes with some rather severe limitations regarding how vendoring works and what you can put in go.mod, and go install doesn't support controlling GOBIN when cross-compiling.

I realize that Git tags are a local concept, and by doing the "wrong" git operations one could come up with a different pseudo-version for the same source code. I am afraid I don't have any solution or suggestion regarding this git misfeature, except to note that even in this case the hash information is recorded correctly, and in every case by the virtue of having access to the local source code the programmer can always do some local operation that has the potential to cause a version mislabeling. Git is just more prome to do this by accident, but the ability is there, always.

I don't have any stats to back this up, but from my experience most corporate source code is built by go build, not go install, and it would be great if somehow Go's notion of versioning would be stamped by go build.

CC @bcmills @mvdan @rsc

[mvdan]

At least speaking personally, for cases like mvdan/sh#519, my intent is to show something like devel ${GIT_SHA} when someone does a local Go build out of a git checkout. If someone is manually cloning and building, as opposed to the advertised and easier go install url@latest, I imagine they know what a git hash is. So what 1.18 is currently shipping with is enough for my needs.

It's true that something like a proper module version might be more useful; a git commit hash doesn't give any hint as to how old a version is, whereas a semver version prefix or a timestamp can give a starting point. So, in principle, I agree with you: 1.18 is a big step forward, but it's still unfortunate that the main module version remains as (devel) for local builds.

However, in practice, I still agree with Jay's comment in #29228 (comment); we shouldn't make such a "locally inferred version" look like a normal version, because it's reasonably likely to be wrong or cause confusion with users.

in every case by the virtue of having access to the local source code the programmer can always do some local operation that has the potential to cause a version mislabeling.

Could you give some examples? I can only think of very unlikely scenarios, such as manually corrupting the module download cache after downloading some dependencies. That cache is read-only by default, and go mod verify exists to double-check the contents too.

With the main module in a git checkout, I can think of multiple scenarios which seem more likely:

• What if I've made a commit or tag but not pushed it?
• What if I've edited some files and not committed them?
• What if two people on two computers make the same tag with different code - would they end up with the same exact module version for different software? If one of them pushes their tag to the internet, would the other's computer be affected by the mismatch?

I think that, if we are to implement something like this, the versions must be somehow different from the canonical and unique versions that get computed from fully published commits and tags. This would make it very clear that the versions are inferred from local state, and not guaranteed to be correct. As a simplistic example, imagine that tagging v1.2.3 locally results in a build whose main module version is devel v1.2.3, but when pushed and go installed, gets the version v1.2.3.

[mvdan]

we shouldn't make such a "locally inferred version" look like a normal version, because it's reasonably likely to be wrong or cause confusion with users.

To add a more concrete example: if we made the change proposed here, and locally inferred versions looked like fully published versions, I would have a harder time trusting the output of shfmt -version when my users report bugs. I would have to update the issue template to also ask: did you build from a modified git checkout?

[4ad]

Could you give some examples? I can only think of very unlikely scenarios, such as manually corrupting the module download cache after downloading some dependencies. That cache is read-only by default, and go mod verify exists to double-check the contents too.

I was thinking of the case where since Go itself doesn't expose its own concept of a version to the program, the users themselves are forced to create their own concepts of a version, either through things like VERSION files, or through some build wrappers. By definition, any such concept is under user's control, and the user can and will make mistakes. In fact, from experience, users try to naively use git tags for this which then fail for precisely the reasons you just explained.

Let me rephrase my point. Go can't enforce any useful properties for the user's notion of a version because it doesn't know about it, and as such if we make userVersion==moduleVersion, the fact that Go can't enforce any properties is neither better nor worse for the user. The user is on the hook for doing the right thing in both cases. In one case the user must properly maintain their VERSION, and in the other case the user must properly maintain their git checkouts.

The user does gain something in the latter case though. They don't have to create build wrappers.

With the main module in a git checkout, I can think of multiple scenarios [which might fail ... ] I think that, if we are to implement something like this, the versions must be somehow different from the canonical and unique versions that get computed from fully published commits and tags. [...] As a simplistic example, imagine that tagging v1.2.3 locally results in a build whose main module version is devel v1.2.3, but when pushed and go installed, gets the version v1.2.3.

I very much agree with this, with one caveat. If the locally checked-out version is identical to a published release, I would expect the version to match the release. If the locally checked-out version can not be guaranteed to match any release, then yes, it should be published with something like devel v1.2.3 (which matches what Go does, but why not v1.2.3-devel or v1.2.3-unknown, which is semver-compatible?).

Unfortunately, I can't imagine how this would work without internet access, and quite often a prerequisite of automated systems running go build is to not go to the Internet.

[4ad]

Hold on, another thought. If we always add the commit hash, and some other metadata to the main module version for local builds, essentially always making them a fully qualified Go pseudo-version, then they will always be different from the published version, so there's no potential for confusion there.

Even better, in semver terms these builds will sort before the published version, which is probably what people want.

For this, what I said earlier about

If the locally checked-out version is identical to a published release, I would expect the version to match the release.

can no longer be true, but perhaps that is ok as long as we come up with a documented and stable convention that describes versioning for local builds (as opposed to just dumping a "devel" in the metadata field).

[bcmills]

The main caveat here, I think, is unpublished tags. If I create a local, unpublished tag for, say, v1.1000.0, then my pseudo-versions will be v1.1000.0-0.2022…, but everyone else's pseudo-versions may be on an arbitrarily lower version (say, v0.8.3-0.2022….

That may or may not be a significant issue, though: if we always use a pseudo-version, we'll at least have the commit hash as a common point of reference even if the base versions differ.

[mvdan]

@4ad right, a local build can't always know what is or isn't published, as requiring a network roundtrip takes us back to square one.

Your idea of trying to stick to semver, and always using some form of pseudo-version which includes a hash, sounds good. With one caveat, though: the commit hash isn't enough to make the version unambiguous, because I can have infinite kinds of uncommitted changes that do not change the HEAD commit hash.

@bcmills good point about tags still messing with pseudo-versions, but at least if we always include a timestamp and some form of unique hash, then I think we're good. With the caveat above about uncommitted changes :)

[mvdan]

We do have another hash available to us, though, which changes whenever any input Go code changes: the build IDs used for the build cache. I seem to recall that one such ID is embedded into binaries, too.

Not ideal, as such a hash also includes build parameters like GOOS or -tags, which don't normally affect versions. But at least it fixed the problem with uncommitted files in VCS.

[4ad]

Yes, uncommitted changes should be explicit in the pseudo-version, but I think we can suffix +, just as we do with Go itself, no?

[seankhliao]

the new buildinfo already records whether the workspace is clean with vcs.modified=true|false

[seankhliao]

we could use one of +local (for clean builds) or +dirty (uncommitted changes, implies local) as the semver build id, attached to a pseudoversion which should make the situation clear enough?

So main will always have a version like

vX.Y.Z-timestamp-commit+local
vX.Y.Z-timestamp-commit+dirty

[hyangah]

What is the main motivation of encoding the local version in pseudo-version style rather than keeping those extra info (timestamp?) as extra metadata fields - if it's not guaranteed that they are always available in the origin or proxies?

It seems like the vcs.time is already there in the build info metadata.

---

BTW, I feel like the main module's version isn't sufficient to describe a tool's behavior in certain cases - go version used to go build, third-party tools dependencies, and go build's behavior change (go.work left over somewhere accidentally?) can affect a tool's behavior. So when triaging issues, I hope we develop best practice using go version -m or richer build info dump rather than relying on the main module version string.

[4ad]

What is the main motivation of encoding the local version in pseudo-version style

The main motivation is that go install does it, and many people expect to have a notion of a program's version available and want it, and because they don't have it with go build, they rely on build wrapers or other workarounds, which are undesirable in the broader Go ecosystem.

encoding the local version in pseudo-version style rather than keeping those extra info (timestamp?) as extra metadata fields

Emphasis mine.

It's not rather than, It doesn't replace the existing metadata fields. If you want to read the metadata, you should read it from those fields instead of parsing the pseudo-version. However, that metadata is useful in disambiguating builds produced by go build from published releases. Presumably we could come with some other kind of metadata for the same purpose, but since pseudo-versions are a de-facto standard in the Go ecosystem, why not reuse it?

I feel like the main module's version isn't sufficient to describe a tool's behavior in certain cases - go version used to go build, third-party tools dependencies, and go build's behavior change (go.work left over somewhere accidentally?) can affect a tool's behavior.

This sounds like an argument to always use the build ID as the version suffix instead of the VCS hash.

So when triaging issues, I hope we develop best practice using go version -m or richer build info dump rather than relying on the main module version string.

I hope so too, but again, I think that discussion is out of scope for this thread, which is more about bringing go build in line with go install and providing a solution for users that avoids build wrappers.

[rsc]

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

[maja42]

As a kind of experience report, I'm using custom build-scripts for years, solely to embed version information of the main module into the executable. When building, I attach the following information:

type BuildInfo struct {
	// Major, Minor, Patch contain the semantic version components.
	// In case of an unofficial build, this version is from a previous commit on the same branch.
	Major, Minor, Patch int
	// If true, a version-tagged commit was built.
	OfficialBuild bool

	// CommitHash is the full hash of the git commit.
	// Note that the actually built source-code is different if LocalChanges is true.
	CommitHash string
	// CommitTimestamp is the timestamp of the git commit.
	// Note that the actually built source-code is different if LocalChanges is true.
	CommitTimestamp time.Time
	// BuildTimestamp contains the timestamp when the project was built.
	BuildTimestamp time.Time

	// LocalChanges specifies if the project directory differed from the commit due to local (uncommitted) changes.
	LocalChanges bool
}

With this kind of information, I'm able to build version-strings however I like. Usually I try to match go's pseudo-version strings, but when I need to stay compatible with the version-scheme from other, non-go projects, I can do so as well.

// VersionString returns the project's semantic version number without a leading 'v'.
// Patterns:
//    <major>.<minor>.<patch>
//        Built from an officially tagged commit (without local changes)
//    0.0.0-<buildTime>
//        Unofficial build. There are no tagged commits yet.
//    <major>.<minor>.<patch*>-<buildTime>
//        Unofficial build. The commit was not tagged, or there were local changes.
//        The used patch-version is +1 compared to the last tagged commit.
//    The build timestamp (yyyymmddhhmmss) is the UTC time when the application was built / ctgover generated the version number.
func (b *BuildInfo) VersionString() string {
	preRelease := ""
        patch := p.Patch
	if !b.OfficialBuild {
		buildTime := b.BuildTimestamp.Format("20060102150405")
		preRelease = "-" + buildTime
                patch++
	}
	return fmt.Sprintf("%d.%d.%d%s", b.Major, b.Minor, patch, preRelease)
}	

The version is printed when the application is started with a -version command-line flag. But I guess go-tools could/should show the same version string.

I don't have anything against adding a build ID, but it wouldn't really solve my problem. My use cases are:

• Identify the source-code / git-commit that was built
• Identify the application's version (for example to detect available updates)
• Identify when the application was built (quickly find out if it super old)
• Compare if two applications are the same, and which one is newer

The previously raised issue that git-tags might only be local was never really an issue in my experience. Version-tags aren't made lightheartedly and are always immediately pushed to the server in the projects I work on.

I really hope we can this kind of information into a go-executable one day, because I would finally be able to get rid of all my build- and tool-scripts.

[rsc]

It sounds like @mvdan and @bcmills have some hesitation around the fact that these pseudo-versions would not correspond to any publicly available version, even though they look like those. That does seem like a reason not to do this.

We now have Git VCS info separately in the builds (as of Go 1.18; try go version -m). Do we need to add a second way to record that information?

[4ad]

It sounds like @mvdan and @bcmills have some hesitation around the fact that these pseudo-versions would not correspond to any publicly available version, even though they look like those.

We can make it unambiguously distinct, for example instead of v1.2.4-0.20191109021931-daa7c04131f5 we could use v1.2.4-0.unpublished.20191109021931-daa7c04131f5 or something like that.

We now have Git VCS info separately in the builds (as of Go 1.18; try go version -m). Do we need to add a second way to record that information?

No, we certainly only need one way to encode VCS info. The suggestion to put VCS info in the metadata field of the pseudo-version was to match the go install behavior, but putting something else there, for example the build id is probably better. The build id also works, and is meaningful when you might not have VCS info, like from a tarball, which is a pretty common case where you'd use go build for. Scratch that idea, without VCS we can't detect the version either.

[ChrisHines]

We can make it unambiguously distinct, for example instead of v1.2.4-0.20191109021931-daa7c04131f5 we could use v1.2.4-0.unpublished.20191109021931-daa7c04131f5 or something like that.

With replace statements in go.mod and the new workspace mode in Go 1.18 it is possible to build Go programs that include local versions of modules besides the main module. For those modules the go tool also lists (devel) for their version.

The new build vcs metadata only helps identify the main module. Adding vcs metadata for all local modules seems valuable and not currently supported. The format suggested above by @4ad would be more informative than (devel). Maybe also including a dirty flag if there are uncommitted local edits.

[rsc]

The new build vcs metadata only helps identify the main module. Adding vcs metadata for all local modules seems valuable and not currently supported.

This may be true, but the concern above seems to be adding vcs metadata that looks like a pseudo-version. It need not, and it probably should not. We can always add that separately; maybe that should be a different proposal. (I think this is the first comment to bring up VCS info for replaced modules that point to other local repos.)

[mvdan]

A thought: if we're only concerned about having a reliable way to always get some useful version for the main module, I think it could be an API of its own, like debug.MainVersion() string. It could first try to get the main module version from https://pkg.go.dev/runtime/debug#ReadBuildInfo, otherwise fall back to VCS information, and otherwise fall back to something that should always work, such as the binary's build ID.

I personally will be implementing logic like that to replace -ldflags=-X=main.version=... in my projects, where I use a default of var version = "(devel)". And I think it should be useful to other projects as well, at least as a good starting point.

Another option, if we want this to also work for library modules, would be debug.OwnVersion, which would do the equivalent but for the module containing the package that's making the function call. Perhaps that would cover @ChrisHines's needs. I maintain some libraries and I admit that reliably knowing my own version could help in terms of logging or capturing debug information.

If the above sounds interesting, I'll happily develop the idea further and create a new proposal. I realise it's not the same as this proposal, but I also think it could be a different solution to the same end-user problem :)

[kortschak]

@mvdan I would very much like to see something like that to replace the boiler place build lines that exist in code at work.

[4ad]

We use the semantic version of the binaries in order to compute API compatibility between different binaries. I am afraid that if your debug.MainVersion() doesn't always return some string that is compatible with semver, we will still have to resort to -ldflags=-X=....

Now, one might object to using the binary version in this way and perhaps recommend using a separately maintained API version instead that is separate from the binary version. I would tend to agree except this is outside my control. I do not have the operational liberty to change this.

[samthanawalla]

Thank you for all your ideas. This is definitely an important feature. After considering all of your ideas and discussing with @matloob and @rsc, we have landed upon this format:

v[tag]+[optional dirty]

When the current commit matches a tagged version.

[optional dirty]

dirty: there are uncommitted changes in the build.
A missing dirty label indicates that the build is ‘clean’ and has no uncommitted changes.

Example:

• v1.2.4
• v1.2.4+dirty

[Pseudo version]+[optional dirty]

When the current commit does not match a tagged version.

Example:

• v1.2.3-0.20240620130020-daa7c0413123+dirty

• v1.2.3-0.20240620130020-daa7c0413123

If you have any feedback, please let us know!
We will try to get this in 1.24.

[apparentlymart]

The proposed format makes sense to me when either the work tree is dirty or the currently-selected commit doesn't exactly match a tag.

It's not clear to me from the most recent comment whether there would also be a special case to use the regular version number alone when the current commit exactly matches a tag. Ideally I'd like for that case to be indistinguishable from the treatment of libraries, but I don't know if there are hurdles that make that infeasible.

If the outcome were to use the proposed format in the dirty or not-tagged case but to use the tag-derived version number when at tag exactly matches then I think that would be sufficient for the codebase I help maintain in my day job to drop its own redundant version number tracking and use the toolchain-generated version information exclusively, which would be great because we'd then get more reliable information for non-release builds (that are always just called "v1.2.3-dev" for us today).

[apparentlymart]

One potential caveat:

Some version constraint systems use lexical ordering to decide which is the newest between two prerelease versions that have the same base version. In that case v1.2.3-devel-anything would sort after v1.2.3-alpha-anything or v1.2.3-beta-anything.

I don't think that's a blocking concern -- it's questionable whether it's ever meaningful to sort development builds relative to release builds anyway -- but wanted to raise it anyway since it was a hazard I've run into in the past in a different context.

[seankhliao]

• What happens when there's no tag at the current commit?
• Sorting before seems a bit weird, especially if there are local changes layered on top of an existing tagged/release version?
• The separator used is -, but semver uses . to separate build identifier components, any specific reason for using -?

[hyangah]

From #50603 (comment)
I thought we'd use the exact tag as the version, with extra build setting info (e.g. VCS info or lack of it, install-vs-build, etc). I am still in favor of the idea because:

• It is human who ultimately consumes the version string. Longer strings are less user friendly. Most products use v1.2.3 form of versioning in the release notes, public tags, and announcements. It will be less obvious for users to connect v1.2.3 release note and v1.2.3-devel-... in the build info.
• The version info is also useful for tools (e.g. vuln scanners) written in different languages and targeted for language-agnostic services. Building more go specific rules beyond the general semver rules can result in bugs (e.g. false positive/negative in vuln scanning service)
• It's unclear what we want to achieve by trying to encode all build details in the version string rather than using the build info setting field.

More specific example:

Let's assume we found a vulnerability in a binary built from a clean checkout of v1.2.3, and it's fixed in v1.2.4. All release note, bug triaging, etc are done with this short tag v1.2.3 most likely, but the released binary has v1.2.3-devel-20240620130020-daa7c0413123 since go build was used. That can be confusing.

When creating a CVE, we should use v1.2.3-devel-20240620130020-daa7c0413123 as the vulnerability introduction version, but use v1.2.4-devel-2024... as the fix version. This is less user-friendly. Moreover, I heard version range comparison involving pseudo versions can be complex. (@golang/vulndb, @neild)

The version in the build info is also used by the Go telemetry. To collect the telemetry, the version string should be explicitly listed in the configuration. I don't think the binary with version v1.2.3 and the binary with v1.2.3-devel-20240620130020-daa7c0413123 are different enough to warrant separated tracking.

[zpavlinovic]

• What happens when there's no tag at the current commit?

I guess v0.0.0 will be used?

• The separator used is -, but semver uses . to separate build identifier components, any specific reason for using -?

Could you expand on that? - is currently used in pseudo versions.

[sudo-bmitch]

• The separator used is -, but semver uses . to separate build identifier components, any specific reason for using -?

Could you expand on that? - is currently used in pseudo versions.

It should be one dash followed by dot separated components: https://semver.org/#spec-item-9

[seankhliao]

The current pseudoversions use different base versions based on existing tags in the current of parent commits:

• vX.0.0-yyyymmddhhmmss-abcdefabcdef is used when there is no known base version. As with all versions, the major version X must match the module’s major version suffix.
• vX.Y.Z-pre.0.yyyymmddhhmmss-abcdefabcdef is used when the base version is a pre-release version like vX.Y.Z-pre.
• vX.Y.(Z+1)-0.yyyymmddhhmmss-abcdefabcdef is used when the base version is a release version like vX.Y.Z. For example, if the base version is v1.2.3, a pseudo-version might be v1.2.4-0.20191109021931-daa7c04131f5.

The dot separator (.)0. is used to ensure these sort before any user provided build identifiers.

Given that we already have existing pseudoversions that can identify commits, I'm not sure why we need a separate format for local builds, beyond marking it as either a local clean or dirty build (maybe build metadata +clean vs +dirty?)

[samthanawalla]

It's not clear to me from the most recent comment whether there would also be a special case to use the regular version number alone when the current commit exactly matches a tag.

I see your point. It would be useful to drop the pseudo version if the current commit matches a tag. My understanding is that they may need to be separate. A local build might inherently be different than one from one that is go install'd and such we don't want to confuse the two. I will discuss more with @rsc and @matloob and circle back.

v1.2.3-devel-anything would sort after v1.2.3-alpha-anything

Interesting point. Like you said, I don't think it would be meaningful to sort a local build against other pre-release versions, but let's add a -0 to have it be less than any pre-releases. So we have v1.2.3-0-devel.

What happens when there's no tag at the current commit?

vX.0.0 if there is no such tag.

Sorting before seems a bit weird, especially if there are local changes layered on top of an existing tagged/release version?

Good point! Let's have it sorted after. Upon further investigation, copying the psuedo-version behavior from go install makes sense here which bumps the version if the commit is newer than the last release.
https://cs.opensource.google/go/go/+/master:src/cmd/vendor/golang.org/x/mod/module/pseudo.go

So we will perform this operation:
vX.Y.(Z+1) if a tag exists.

The separator used is -, but semver uses . to separate build identifier components, any specific reason for using -?

This we're not completely sure on. But I suppose a combination of '.' and '-' makes more sense.

Taking into account the above points, maybe instead we should do:

v[X.Y.(Z+1)]-0.[timestamp].devel-[commit]+[optional dirty]

Given that we already have existing pseudoversions that can identify commits, I'm not sure why we need a separate format for local builds

I agree with you. I think it makes sense to closely follow the existing structure from: https://cs.opensource.google/go/go/+/master:src/cmd/vendor/golang.org/x/mod/module/pseudo.go

@hyangah
I suppose it comes down to the intent of how these pseudo-versions will be used. It's not clear to me if there should be a clear separation between a local build and one based on a go install. If we drop the pseudo version when the current commit matches the tagged version, then that might clear up some confusion.
Let me discuss this more in depth with @rsc and @matloob and I will update when I have a clearer answer.

Thanks for the help guys.

I will update my original comment to reflect these changes.

[mvdan]

I want to reiterate what @hyangah said - as of 2022, and when the proposal was accepted, we had already reached consensus that a local build of a commit on a semver tag should result in a module version reflecting just that semver string. See #50603 (comment) for example. I don't think new information has come to light since then, so I'd be very confused if we suddenly decided to implement something else.

[zpavlinovic]

Further, if a proposed pseudo-version of a clean local commit with a semver tag is syntactically different from the semver tag, then how does that affect version.Compare? It should return 0 imo, but I have no idea how one would actually implement that.

[matloob]

@hyangah @mvdan About stamping the tagged version without any suffixes when doing a go build in a clean repo:

I've been thinking about this and I can't prove to myself that we'd get the same build running go build package from within the module and from running go install package@version. It seems like at the least we'd have to fall back to adding a suffix if there's a replacement or exclude because in those cases go install would refuse to do the build.

I'm also not totally sure about how module pruning affects a module loaded from go install package@version vs go build. Looking at the comment @mvdan linked it looks that Bryan thought this was okay, but I would think that going through go install package@version vs go build the lazy loading horizon would be at a different level because with go install package@version, the module containing the package isn't treated as the main module? I'll try to think about this some more.

It's likely there's no issue there and I'm overthinking it. It might also be that these issues don't matter because the version is not meant treated as 100% accurate.

[samthanawalla]

@zpavlinovic
how does that affect version.Compare?

I believe version.Compare only compares go versions.
I think you meant semantically comparing module versions?

If we cannot guarantee the same behavior of go install and go build with @matloob's concerns then it might make sense to add a +build suffix? (similar idea to what Sean had suggested with +local)
i.e. v1.2.4+build
This would compare equally to v1.2.4 but imply that they were built differently.

[mvdan]

It might also be that these issues don't matter because the version is not meant treated as 100% accurate.

That is my understanding from the previous consensus. go install pkg@version via a GOPROXY blindly trusts the info from the proxy to produce a module version. Similarly, with GOPROXY=off, we blindly trust the info from the original VCS state, which can easily be altered in many cases. Blindly trusting the local VCS state does not seem any worse in this respect - if anything, it's consistent.

I don't have a strong opinion on a suffix like +build or +local to distinguish local builds, but I worry it could easily confuse users and cause issues for module developers who now may need to deal with this suffix inconsistency. If the produced build is otherwise equivalent to go install pkg@version with GOPROXY=off, then I definitely think the resulting module version should be the same.

It's also worth noting that one could often use the presence and contents of the stamped -buildvcs metadata to detect that a build was made locally and a module version was derived from it. If we only stamped a VCS-derived module version for a local build when -buildvcs was enabled, then a developer could use the presence of the VCS information to tell that a module version was derived from the local VCS state. That is what I would find most intuitive as both a user and developer.

[rsc]

I too am confused why we would define a new pseudo-version syntax instead of using the existing algorithm and derivation code. Let's talk more about this next time we meet, @matloob and @samthanawalla.

[samthanawalla]

@rsc @matloob and I discussed this today.

I have revised my original comment to reflect the decision we came to. See #50603 (comment)

When the current commit matches a tagged version we will use v[tag].

When the current commit does not match a tagged version or there are uncommitted changes, we'll use the existing pseudo version format. along with an optional dirty tag.

(We dropped the devel and the +build)

[DavidGamba]

Are uncommitted changes only considered for the directory where the go.mod lives? I work in monorepo environments and rarely ever achieve a full clean repo.

[samthanawalla]

@DavidGamba
Are uncommitted changes only considered for the directory where the go.mod lives?

We were planning to rely on what the VCS state is, I.e. git status.
I don't think it makes sense to only consider the directory where go.mod lives because it introduces additional states to consider which I think may make the version info more confusing. But I could be wrong.

However as a compromise, would v[tag]+dirty work for your use case?

If your current commit matches a tagged version but you have uncommitted changes, you would get v[tag]+dirty instead of [pseudoversion]+dirty.

[DavidGamba]

I would prefer to be able to push a binary as is from my machine if there are no changes in the the given go module. Other than a go.work file and possible env vars there shouldn't be any dirty files affecting the go binary itself so marking the binary as dirty when there are no changes in the module itself seems overly cautious.

it introduces additional states to consider

I am not sure I know enough about Go to know anything else other than the go.work and env vars that introduce additional states. I would love to learn a bit more about what else affects a go module.

At the end of the day, having the version stamped will be a win even if I can only get the non-dirty version out of CI or a clean clone.

[samthanawalla]

By additional states I meant to say version control states.

I do get your point but a tag is more a property of the repo and not just the main module. Changes to the repo as a whole will reflect accordingly in the stamped version.

While it may be overly cautious, I don't think we will support this use case as of now. But that could change in the future if necessary.

Updated #50603 comment to include v[tag]+dirty use case.

[matloob]

@DavidGamba I would be interested in understanding your use case better. Our expectation is that those planning to do a build of a go program at a given version would check out the appropriate version and do a clean build. Our plan is to reuse the vcs.modified field in the buildinfo in determining whether a build is clean. That would help avoid doing extra work for what we believe is an uncommon case. But if it isn't an uncommon case we'd like to know.

[zpavlinovic]

vcs.modified seems to be set here. My understanding of the code is that this value is false by default unless one of known versioning systems is used. For those systems, status command is used to get the value for modified using the current working directory.

I would prefer to be able to push a binary as is from my machine if there are no changes in the the given go module. Other than a go.work file and possible env vars there shouldn't be any dirty files affecting the go binary itself so marking the binary as dirty when there are no changes in the module itself seems overly cautious.

The more and more I think about this, the more I get the feeling that having a completely precise solution is either extremely hard or impossible.

If a module has a replace directive pointing to a local directory outside of the module, then changing that replacing directory content could result in a different binary. To make things more complicated, this replacing directory might be outside of a repo where the module is.

It seems to me that the current approach is making a decent compromise. It will cover the more common case where the replacing module is in the same repo. Of course, it might add +dirty if part of a repo completely unrelated to module is being changed.

Regarding monorepo, it seems that the current approach will always have vcs.modified set to true. An example is svn (it does not have a Status method so computing modified will be skipped). It would be good to verify that.

[DavidGamba]

My use case is not a major use case since official builds will come from CI. It is just in those cases where you want to push something out that doesn't have a pipeline yet. Cloning a clean repo for those is not a major inconvenience and worst case the binary will just have the +dirty label.