diff options
Diffstat (limited to 'content/v2-go-modules.article')
| -rw-r--r-- | content/v2-go-modules.article | 33 |
1 files changed, 17 insertions, 16 deletions
diff --git a/content/v2-go-modules.article b/content/v2-go-modules.article index cb8b7be..59d86de 100644 --- a/content/v2-go-modules.article +++ b/content/v2-go-modules.article @@ -1,19 +1,20 @@ -Go Modules: v2 and Beyond +# Go Modules: v2 and Beyond 7 Nov 2019 Tags: tools, versioning +Summary: This post is part 4 in a series. Jean de Klerk Tyler Bui-Palsulich -* Introduction +## Introduction This post is part 4 in a series. -- Part 1 — [[/using-go-modules][Using Go Modules]] -- Part 2 — [[/migrating-to-go-modules][Migrating To Go Modules]] -- Part 3 — [[/publishing-go-modules][Publishing Go Modules]] -- *Part*4*—*Go*Modules:*v2*and*Beyond* (this post) + - Part 1 — [Using Go Modules](/using-go-modules) + - Part 2 — [Migrating To Go Modules](/migrating-to-go-modules) + - Part 3 — [Publishing Go Modules](/publishing-go-modules) + - **Part 4 — Go Modules: v2 and Beyond** (this post) As a successful project matures and new requirements are added, past features and design decisions might stop making sense. Developers may want to integrate @@ -29,10 +30,10 @@ breaking changes are expected by users. For projects which are declared stable version. This post explores major version semantics, how to create and publish a new major version, and how to maintain multiple major versions of a module. -* Major versions and module paths +## Major versions and module paths Modules formalized an important principle in Go, the -[[https://research.swtch.com/vgo-import][*import*compatibility*rule*]]: +[**import compatibility rule**](https://research.swtch.com/vgo-import): If an old package and a new package have the same import path, the new package must be backwards compatible with the old package. @@ -48,8 +49,8 @@ their package imports and module requirements to `github.com/googleapis/gax-go/v The need for major version suffixes is one of the ways Go modules differs from most other dependency management systems. Suffixes are needed to solve -the [[https://research.swtch.com/vgo-import#dependency_story][diamond dependency problem]]. -Before Go modules, [[http://gopkg.in][gopkg.in]] allowed package maintainers to +the [diamond dependency problem](https://research.swtch.com/vgo-import#dependency_story). +Before Go modules, [gopkg.in](http://gopkg.in) allowed package maintainers to follow what we now refer to as the import compatibility rule. With gopkg.in, if you depend on a package that imports `gopkg.in/yaml.v1` and another package that imports `gopkg.in/yaml.v2`, there is no conflict because the two `yaml` packages @@ -59,7 +60,7 @@ command accepts the `.v2` in `gopkg.in/yaml.v2` as a valid major version suffix. This is a special case for compatibility with gopkg.in: modules hosted at other domains need a slash suffix like `/v2`. -* Major version strategies +## Major version strategies The recommended strategy is to develop `v2+` modules in a directory named after the major version suffix. @@ -69,7 +70,7 @@ the major version suffix. /v2/go.mod → module github.com/googleapis/gax-go/v2 This approach is compatible with tools that aren't aware of modules: file paths -within the repository match the paths expected by `go`get` in `GOPATH` mode. +within the repository match the paths expected by `go get` in `GOPATH` mode. This strategy also allows all major versions to be developed together in different directories. @@ -82,7 +83,7 @@ The examples in this post will follow the major version subdirectory strategy, since it provides the most compatibility. We recommend that module authors follow this strategy as long as they have users developing in `GOPATH` mode. -* Publishing v2 and beyond +## Publishing v2 and beyond This post uses `github.com/googleapis/gax-go` as an example: @@ -132,10 +133,10 @@ adding a `v2/` suffix to the module path: $ go mod edit -module github.com/googleapis/gax-go/v2 v2/go.mod $ -Note that the `v2` version is treated as a separate module from the `v0`/`v1` +Note that the `v2` version is treated as a separate module from the `v0 / v1` versions: both may coexist in the same build. So, if your `v2+` module has multiple packages, you should update them to use the new `/v2` import path: -otherwise, your `v2+` module will depend on your `v0`/`v1` module. For example, +otherwise, your `v2+` module will depend on your `v0 / v1` module. For example, to update all `github.com/my/project` references to `github.com/my/project/v2`, you can use `find` and `sed`: @@ -165,7 +166,7 @@ At that point, there are now two major versions to maintain. Backwards compatible changes and bug fixes will lead to new minor and patch releases (for example, `v1.1.0`, `v2.0.1`, etc.). -* Conclusion +## Conclusion Major version changes result in development and maintenance overhead and require investment from downstream users to migrate. The larger the project, |