docs: add ADR 053 Go Module Refactoring #11799
Conversation
github-actions
bot
added
the
T: ADR
|
@marbar3778 where are we with the domain name for the repos? |
| discussed below in the [Consequences](#consequences) section), but the | ||
| approach being adopted is the following: | ||
| * a go module should generally be scoped to a specific coherent set of | ||
| functionality (such as math, errors, store, etc.) |
There was a problem hiding this comment.
Maybe it's worth mentioning that each SDK module will be its own go module too?
| being tagged as `v1.0.0` to accommodate the possibility that they may be | ||
| better served by a standalone repository in the future | ||
| * all go modules should follow the guidelines in https://go.dev/blog/module-compatibility | ||
| before `v1.0.0` is tagged and should make use of `internal` packages to limit |
There was a problem hiding this comment.
For x/* go modules, there some probably more guidelines, right? Some unanswered questions I have, which I think could go into this ADR:
- do state-machine breaking changes require a major bump?
- client-breaking changes?
- CLI?
|
|
||
| * there will be more go module versions to update in the SDK itself and | ||
| per-project, although most of these will hopefully be indirect | ||
|
|
There was a problem hiding this comment.
Another negative one is that I think we need tooling for publishing go modules. Similar to lerna for go modules.
Say foo@1.0.0 has a security fix, so we release foo@1.0.1. And we want a new patch version for each of {bar,baz,qux} go modules. Currently we would need to update deps manually (or using dependabot), and then tag these individually.
There was a problem hiding this comment.
I think a Tooling subsection would actually make sense, but can be left empty for this version of the ADR, since this ADR is still only proposed.
| In general, it seems safer to just create a new module path (appending v2, v3, etc. | ||
| if necessary), rather than trying to make an old package a new module. |
There was a problem hiding this comment.
This sentence is a bit confusing to me. It seems for errors, we did create a new module from an old package.
There was a problem hiding this comment.
Another thing that's not clear for me is: when bumping a major version, do we:
- rename in go.mod
cosmossdk.io/foo->cosmossdk.io/foo/v2, and tagfoo/v2.0.0 - or no rename in go.mod, simply tag
foo/v2.0.0
There was a problem hiding this comment.
My understanding is that go.mod module directive has to be updated, but moving code to subdirectory is optional:
If the module is released at major version 2 or higher, the module path must end with a major version suffix like /v2. This may or may not be part of the subdirectory name. For example, the module with path golang.org/x/repo/sub/v2 could be in the /sub or /sub/v2 subdirectory of the repository golang.org/x/repo.
| * standalone pieces of software will reach `v1.0.0` sooner | ||
| * new features to specific functionality will be released sooner | ||
|
|
||
| ### Negative |
There was a problem hiding this comment.
Currently SDK modules depend on other modules' public APIs. With independent go module versioning, we might need to have compatibility tables like staking@v5 is compatible with bank@{v3,v4} but not with bank@v2 etc, is that correct?
It seems this can be elegantly solved by ADR-033 and the api/ folder (no go API compatibility, on proto comptability), but until then, is that a concern to you too @aaronc ?
Description
This adds an ADR to describe our process of refactoring the SDK into standalone go modules as discussed in #10582 and started in #10779 and #11788.
rendered
Author Checklist
All items are required. Please add a note to the item if the item is not applicable and
please add links to any relevant follow up issues.
I have...
!to the type prefix if API or client breaking changeCHANGELOG.mdReviewers Checklist
All items are required. Please add a note if the item is not applicable and please add
your handle next to the items reviewed if you only reviewed selected items.
I have...
!in the type prefix if API or client breaking change