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.

Sign up for GitHub

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: add documentation for go.work.sum #51941

Closed
samherrmann opened this issue Mar 25, 2022 · 7 comments
Closed

cmd/go: add documentation for go.work.sum #51941

samherrmann opened this issue Mar 25, 2022 · 7 comments
Labels
Documentation Issues describing a change to documentation. NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Milestone
Backlog

Comments

@samherrmann
Copy link

samherrmann commented Mar 25, 2022 •
edited
Loading

With the release of Go 1.18, we now have workspaces. From my findings, workspaces appear to be documented in the following locations:

None of these locations however make mention of the go.work.sum file. The go.work.sum file was however described in the proposal.

This issue is to bring the description of the go.work.sum file from the proposal into the official documentation.
@gopherbot gopherbot added the Documentation Issues describing a change to documentation. label Mar 25, 2022
@seankhliao seankhliao changed the title go/cmd: Add documentation for go.work.sum cmd/go: Add documentation for go.work.sum Mar 25, 2022
@mknyszek
Copy link
Contributor

CC @matloob

@mknyszek mknyszek added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Mar 25, 2022
@mknyszek mknyszek changed the title cmd/go: Add documentation for go.work.sum cmd/go: add documentation for go.work.sum Mar 25, 2022
@mknyszek mknyszek added this to the Backlog milestone Mar 25, 2022
@espadolini espadolini mentioned this issue Apr 20, 2022
Merged
@katexochen katexochen mentioned this issue May 31, 2022
Merged
@julienrbrt julienrbrt mentioned this issue Jul 21, 2022
Merged
19 tasks
@bcmills bcmills mentioned this issue Sep 15, 2022
Open
@pellared pellared mentioned this issue May 10, 2023
Closed
@codyoss
Copy link
Member

codyoss commented May 16, 2023

I recently added go.work to a large project and another maintainer asked me about the sum file and it left me a bit clueless as well. Seems oddly missing from https://go.dev/ref/mod#workspaces

@mvrahden
Copy link

I agree, a little piece of documentation on the purpose of this file and its insides would be great.

@erdii erdii mentioned this issue Aug 3, 2023
Merged
3 tasks
@nickzelei nickzelei mentioned this issue Sep 7, 2023
Merged
@MarianMacik
Copy link

I also came across a few situations where the go.work.sum file changes seemingly for no reason, even shrinking in size despite new modules were added to the workspace. So I would appreciate some documentation about its purpose.

@calebschoepp
Copy link

I also came across a few situations where the go.work.sum file changes seemingly for no reason, even shrinking in size despite new modules were added to the workspace. So I would appreciate some documentation about its purpose.

I've been really struggling with this myself. My go.work.sum seems to be constantly changing. I don't understand the purpose of it, why its changing, and whether it is something I should track in git.

@hoangdv2429 hoangdv2429 mentioned this issue Dec 14, 2023
Closed
5 tasks
@geoknee geoknee mentioned this issue Jan 30, 2024
Merged
@gopherbot
Copy link
Contributor

Change https://go.dev/cl/563855 mentions this issue: _content/ref/mod: document go.work.sum files

@matloob
Copy link
Contributor

matloob commented Feb 13, 2024

I sent out CL 563855 to add documentation to golang.org/ref/mod, which seems to be the best place for it.

@calebschoepp Usually go.work files shouldn't be checked in, so go.work.sum files shouldn't be checked in either. But if you are checking in your go.work file it makes sense to check in the go.work.sum file for consistency for the same reason that a go.sum is checked in: to guarantee that others doing a build in your repo are getting the same results. Maybe we could add a line about that to the text proposed for 53502.

Merged
5 tasks
brandur added a commit to riverqueue/river that referenced this issue Dec 28, 2024
@brandur
Remove go.work.sum from version control
c67d36b 
I'd like to propose that we remove `go.work.sum` from version control.
I'd say in general going to workspaces has improved 95%+ of workflows,
but there are a couple annoying sharp edges. The main noticeable one is
that on any new release versions in `go.work.sum` get updated, forcing
the change to be checked in with a separate PR.

Reading more about `go.work.sum`, I found that the Go developers didn't
even bother to document it for two full years, only doing so reluctantly
earlier this year [1]. Its purpose is to track dependencies that are
used in the workspace but not part of any normal modules [2]:

> The go command will maintain a go.work.sum file that keeps track of
> hashes used by the workspace that are not in collective workspace
> modules’ go.sum files.

In River, only the modules, not the workspace, are public entities used
in other projects, and all of their builds are fully reproducible
because they all have `go.sum`. `go.work.sum` tracks some extra stuff,
but I don't think any of it is crucial to what River's users are
actually working with.

Furthermore, I learned that the Go docs actually recommend not checking
in `go.work` in many cases:

> It is generally inadvisable to commit go.work files into version
control systems, for two reasons:
>
> * A checked-in go.work file might override a developer’s own go.work
>   file from a parent directory, causing confusion when their use
>   directives don’t apply.
>
> * A checked-in go.work file may cause a continuous integration (CI)
>   system to select and thus test the wrong versions of a module’s
>   dependencies. CI systems should generally not be allowed to use the
>   go.work file so that they can test the behavior of the module as it
>   would be used when required by other modules, where a go.work file
>   within the module has no effect.
>
> That said, there are some cases where committing a go.work file makes
> sense. For example, when the modules in a repository are developed
> exclusively with each other but not together with external modules,
> there may not be a reason the developer would want to use a different
> combination of modules in a workspace. In that case, the module author
> should ensure the individual modules are tested and released properly.

I think the last paragraph applies more to River -- it's a clear UX
improvement and we're all working in a fairly consistent environment
without using any other external modules, but even so, if it's often
safe that a `go.work` could be omitted, I think there's a good argument
that `go.work.sum` could be omitted too.

I tried this in a branch and `go get`ing River from another test
project, and the removal of `go.work.sum` doesn't seem to have any
negative effect. I'd like to propose that we try removing it from Git
for a while and just see if there are any noticeable problems. I don't
think there will be, and this will purely be beneficial as it lets us
avoid needing to bump the file on every release,  but we can always add
it back in case that turns out to be wrong.

[1] golang/go#51941
[2] https://go.dev/ref/mod#workspaces
@brandur brandur mentioned this issue Dec 28, 2024
Merged
brandur added a commit to riverqueue/river that referenced this issue Dec 28, 2024
@brandur
Remove go.work.sum from version control (#712)
ea9afdb 
I'd like to propose that we remove `go.work.sum` from version control.
I'd say in general going to workspaces has improved 95%+ of workflows,
but there are a couple annoying sharp edges. The main noticeable one is
that on any new release versions in `go.work.sum` get updated, forcing
the change to be checked in with a separate PR.

Reading more about `go.work.sum`, I found that the Go developers didn't
even bother to document it for two full years, only doing so reluctantly
earlier this year [1]. Its purpose is to track dependencies that are
used in the workspace but not part of any normal modules [2]:

> The go command will maintain a go.work.sum file that keeps track of
> hashes used by the workspace that are not in collective workspace
> modules’ go.sum files.

In River, only the modules, not the workspace, are public entities used
in other projects, and all of their builds are fully reproducible
because they all have `go.sum`. `go.work.sum` tracks some extra stuff,
but I don't think any of it is crucial to what River's users are
actually working with.

Furthermore, I learned that the Go docs actually recommend not checking
in `go.work` in many cases:

> It is generally inadvisable to commit go.work files into version
control systems, for two reasons:
>
> * A checked-in go.work file might override a developer’s own go.work
>   file from a parent directory, causing confusion when their use
>   directives don’t apply.
>
> * A checked-in go.work file may cause a continuous integration (CI)
>   system to select and thus test the wrong versions of a module’s
>   dependencies. CI systems should generally not be allowed to use the
>   go.work file so that they can test the behavior of the module as it
>   would be used when required by other modules, where a go.work file
>   within the module has no effect.
>
> That said, there are some cases where committing a go.work file makes
> sense. For example, when the modules in a repository are developed
> exclusively with each other but not together with external modules,
> there may not be a reason the developer would want to use a different
> combination of modules in a workspace. In that case, the module author
> should ensure the individual modules are tested and released properly.

I think the last paragraph applies more to River -- it's a clear UX
improvement and we're all working in a fairly consistent environment
without using any other external modules, but even so, if it's often
safe that a `go.work` could be omitted, I think there's a good argument
that `go.work.sum` could be omitted too.

I tried this in a branch and `go get`ing River from another test
project, and the removal of `go.work.sum` doesn't seem to have any
negative effect. I'd like to propose that we try removing it from Git
for a while and just see if there are any noticeable problems. I don't
think there will be, and this will purely be beneficial as it lets us
avoid needing to bump the file on every release,  but we can always add
it back in case that turns out to be wrong.

[1] golang/go#51941
[2] https://go.dev/ref/mod#workspaces
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Documentation Issues describing a change to documentation. 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
9 participants
@mknyszek @codyoss @samherrmann @MarianMacik @gopherbot @seankhliao @matloob @calebschoepp @mvrahden