proposal: put package cm in its own module

[ydnar]

Problem

Currently, there is a single Go module (go.bytecodealliance.org) with a go.mod file at the root of this repository. The root module includes a number of dependencies, all of which are used in packages such as wit and wit/bindgen for development-time code generation.

Package cm is the sole runtime package in this module, intended to be imported by programs that import code generated by wit-bindgen-go. Package cm has no dependencies other than the Go standard library, which makes it suitable for inclusion into a wide variety of Go programs (including the Go standard library).

Proposal

We propose to put package cm into its own module: go.bytecodealliance.org/cm. This would be a breaking change, requiring users to directly add the module to their go.mod file via go get go.bytecodealliance.org/cm.

• The repository for package cm would remain this repo.
• The import path for package cm would remain the same: go.bytecodealliance.org/cm.
• Each module (root, cm, etc.) would need its own version. Module cm would start with its own version tag cm/v0.1.0, and the root module would be updated to depend on it.
• Each module would contain its own CHANGELOG.md and README.md, to reflect the updated version(s).
• The release workflow (release.yaml) would only apply to the root module, as long as individual sub-modules do not have executable binaries.
• Changes to the release process must be reflected in RELEASE.md.
  • Consider adding a RELEASE.md file to module cm.

Tagging

One consideration is the versioning of package cm (and therefore the module it sits in). Go can import modules in a subdirectory of a repo as long as a version tag exists that match the directory name (package path). To release a new version of package cm, we must create a new tag, e.g. cm/v0.1.0.

Dependencies

Currently, packages in the root module depend on package cm (but not vice-versa). Changes to package cm that the root module depends on will need to be executed in sequence.

Implementation

An implementation of this proposal is at #255.

Tasks

Preview Give feedback

1. Merge cm: extract package cm into its own distinct module #255
2. Create PR for prepping cm/v0.1.0
3. Merge preparation PR for cm/v0.1.0
4. Create tag cm/v0.1.0-pre.1 and test
5. Create tag cm/v0.1.0
6. Create release branch for v0.5.0
7. Test that v0.5.0 can depend on cm/v0.1.0-pre.1
8. In v0.5.0 branch, verify dependency on cm/v0.1.0
9. Merge v0.5.0 branch
10. Create v0.5.0 tag

[ydnar]

cc @Mossaka @lxfontes

Would love your thoughts on this.

[Mossaka]

I think this is the right step to reduce downstream dependency footprints and clarify its role as a standalone package to be imported by many Go programs that use cm types, especially when I added wazero as a dependency in #252.

The version lockstep makes sense.

We propose to put package cm into its own module

Regarding breaking changes, personally I think it's fine since we are in a pre 1.0 version.

Something to consider: we can provide a grace period where cm code is available in both old and new locations and accompanied by a deprecation notice and go.mod replace directive.

[ydnar]

If a program already depends on go.bytecodealliance.org today, and upgrades to a hypothetical v0.5.0 which itself depends on go.bytecodealliance.org/[email protected], then package cm and its module dependency should be pulled in transitively.

I’ll try prototyping this elsewhere to verify this can happen.

[ydnar]

It looks like updating the tags in lock step is not possible, particularly when the root module depends on module go.bytecodealliance.org/cm. I’ve updated the proposal to reflect this.

1. Development process for the repo as a whole proceeds as usual. Changes can be made to the root module as well as package cm.
2. If there are changes to package cm, then these are noted in a new cm/CHANGELOG.md file.
3. A new version of package cm is released with its own version number.
4. The root module is updated to depend on the new version of package cm prior to cutting a new release of the root module.

[lxfontes]

👍
we came full circle with bytecodealliance/governance#72 🌈

[ydnar]

Thanks everyone!