diff options
Diffstat (limited to 'content/versioning-proposal.article')
| -rw-r--r-- | content/versioning-proposal.article | 65 |
1 files changed, 33 insertions, 32 deletions
diff --git a/content/versioning-proposal.article b/content/versioning-proposal.article index 92c8f54..e85ca3d 100644 --- a/content/versioning-proposal.article +++ b/content/versioning-proposal.article @@ -1,13 +1,14 @@ -A Proposal for Package Versioning in Go +# A Proposal for Package Versioning in Go 26 Mar 2018 Tags: tools, versioning +Summary: Eight years ago, the Go team introduced `goinstall` (which led to `go get`) and with it the decentralized, URL-like import paths that Go developers are familiar with today. After we released `goinstall`, one of the first questions people asked was how to incorporate version information. We admitted we didn’t know. For a long time, we believed that the problem of package versioning would be best solved by an add-on tool, and we encouraged people to create one. The Go community created many tools with different approaches. Each one helped us all better understand the problem, but by mid-2016 it was clear that there were now too many solutions. We needed to adopt a single, official tool. Russ Cox -* Introduction +## Introduction Eight years ago, the Go team introduced `goinstall` -(which led to `go`get`) +(which led to `go get`) and with it the decentralized, URL-like import paths that Go developers are familiar with today. After we released `goinstall`, one of the first questions people asked @@ -25,17 +26,17 @@ After a community discussion started at GopherCon in July 2016 and continuing in we all believed the answer would be to follow the package versioning approach exemplified by Rust’s Cargo, with tagged semantic versions, a manifest, a lock file, and a -[[https://research.swtch.com/version-sat][SAT solver]] to decide which versions to use. +[SAT solver](https://research.swtch.com/version-sat) to decide which versions to use. Sam Boyer led a team to create Dep, which followed this rough plan, and which we intended to serve as the model for `go` command integration. But as we learned more about the implications of the Cargo/Dep approach, it became clear to me that Go would benefit from changing some of the details, especially concerning backwards compatibility. -* The Impact of Compatibility +## The Impact of Compatibility The most important new feature of -[[https://blog.golang.org/preview-of-go-version-1][Go 1]] +[Go 1](https://blog.golang.org/preview-of-go-version-1) was not a language feature. It was Go 1’s emphasis on backwards compatibility. Until that point we’d issued stable release @@ -44,21 +45,21 @@ each with significant incompatible changes. We observed significant acceleration in interest and adoption immediately after the release of Go 1. We believe that the -[[https://golang.org/doc/go1compat.html][promise of compatibility]] +[promise of compatibility](https://golang.org/doc/go1compat.html) made developers feel much more comfortable relying on Go for production use and is a key reason that Go is popular today. Since 2013 the -[[https://golang.org/doc/faq#get_version][Go FAQ]] +[Go FAQ](https://golang.org/doc/faq#get_version) has encouraged package developers to provide their own users with similar expectations of compatibility. -We call this the _import_compatibility_rule_: +We call this the _import compatibility rule_: “If an old package and a new package have the same import path, the new package must be backwards compatible with the old package.” Independently, -[[http://semver.org/][semantic versioning]] -has become the _de_facto_ +[semantic versioning](http://semver.org/) +has become the _de facto_ standard for describing software versions in many language communities, including the Go community. Using semantic versioning, later versions are expected to be @@ -71,7 +72,7 @@ If we adopt semantic versioning for Go packages, as most Go developers expect, then the import compatibility rule requires that different major versions must use different import paths. -This observation led us to _semantic_import_versioning_, +This observation led us to _semantic import versioning_, in which versions starting at v2.0.0 include the major version in the import path: `my/thing/v2/sub/pkg`. @@ -86,7 +87,7 @@ When I realized this, the logical necessity surprised me. I was also surprised to realize that there is a second, independent logical route to semantic import versioning: -[[https://talks.golang.org/2016/refactor.article][gradual code repair]] +[gradual code repair](https://talks.golang.org/2016/refactor.article) or partial code upgrades. In a large program, it’s unrealistic to expect all packages in the program to update from v1 to v2 of a particular dependency at the same time. @@ -95,7 +96,7 @@ while other parts have upgraded to v2. But then the program’s build, and the program’s final binary, must include both v1 and v2 of the dependency. Giving them the same import path would lead to confusion, -violating what we might call the _import_uniqueness_rule_: +violating what we might call the _import uniqueness rule_: different packages must have different import paths. The only way to have partial code upgrades, import uniqueness, _and_ semantic versioning @@ -131,7 +132,7 @@ import compatibility simplifies version selection, which is the problem of deciding which package versions to use for a given build. The constraints of Cargo and Dep make version selection equivalent to -[[https://research.swtch.com/version-sat][solving Boolean satisfiability]], +[solving Boolean satisfiability](https://research.swtch.com/version-sat), meaning it can be very expensive to determine whether a valid version configuration even exists. And then there may be many valid configurations, @@ -141,7 +142,7 @@ a trivial, linear-time algorithm to find the single best configuration, which always exists. This algorithm, which I call -[[https://research.swtch.com/vgo-mvs][_minimal_version_selection_]], +[_minimal version selection_](https://research.swtch.com/vgo-mvs), in turn eliminates the need for separate lock and manifest files. It replaces them with a single, short configuration file, edited directly by both developers and tools, @@ -161,7 +162,7 @@ by introducing semantic import versioning eliminates that complexity, leading to a much simpler system. -* Progress, a Prototype, and a Proposal +## Progress, a Prototype, and a Proposal Dep was released in January 2017. Its basic model—code tagged with @@ -191,7 +192,7 @@ I realized that our old advice about import compatibility implied semantic import versioning. That seemed like a real breakthrough. I wrote a first draft of what became my -[[https://research.swtch.com/vgo-import][semantic import versioning]] +[semantic import versioning](https://research.swtch.com/vgo-import) blog post, concluding it by suggesting that Dep adopt the convention. I sent the draft to the people I’d been talking to, @@ -204,7 +205,7 @@ and I set out to do that. In mid-December, I discovered that import compatibility and semantic import versioning together allowed -cutting version selection down to [[https://research.swtch.com/vgo-mvs][minimal version selection]]. +cutting version selection down to [minimal version selection](https://research.swtch.com/vgo-mvs). I wrote a basic implementation to be sure I understood it, I spent a while learning the theory behind why it was so simple, and I wrote a draft of the post describing it. @@ -226,7 +227,7 @@ the approach was clearly viable. I spent the first three weeks of February turning the wrapper into a full versioned `go` command, `vgo`; writing drafts of a -[[https://research.swtch.com/vgo][blog post series introducing `vgo`]]; +[blog post series introducing `vgo`](https://research.swtch.com/vgo); and discussing them with Sam Boyer, the package management working group, and the Go team. @@ -237,26 +238,26 @@ In addition to the core ideas of import compatibility, semantic import versioning, and minimal version selection, the `vgo` prototype introduces a number of smaller but significant changes motivated by eight years of -experience with `goinstall` and `go`get`: -the new concept of a [[https://research.swtch.com/vgo-module][Go module]], +experience with `goinstall` and `go get`: +the new concept of a [Go module](https://research.swtch.com/vgo-module), which is a collection of packages versioned as a unit; -[[https://research.swtch.com/vgo-repro][verifiable and verified builds]]; +[verifiable and verified builds](https://research.swtch.com/vgo-repro); and -[[https://research.swtch.com/vgo-cmd][version-awareness throughout the `go` command]], +[version-awareness throughout the `go` command](https://research.swtch.com/vgo-cmd), enabling work outside `$GOPATH` and the elimination of (most) `vendor` directories. -The result of all of this is the [[https://golang.org/design/24301-versioned-go][official Go proposal]], +The result of all of this is the [official Go proposal](https://golang.org/design/24301-versioned-go), which I filed last week. Even though it might look like a complete implementation, it’s still just a prototype, one that we will all need to work together to complete. -You can download and try the `vgo` prototype from [[https://golang.org/x/vgo][golang.org/x/vgo]], +You can download and try the `vgo` prototype from [golang.org/x/vgo](https://golang.org/x/vgo), and you can read the -[[https://research.swtch.com/vgo-tour][Tour of Versioned Go]] +[Tour of Versioned Go](https://research.swtch.com/vgo-tour) to get a sense of what using `vgo` is like. -* The Path Forward +## The Path Forward The proposal I filed last week is exactly that: an initial proposal. I know there are problems with it that the Go team and I can’t see, @@ -265,11 +266,11 @@ The goal of the proposal feedback process is for us all to work together to identify and address the problems in the current proposal, to make sure that the final implementation that ships in a future Go release works well for as many developers as possible. -Please point out problems on the [[https://golang.org/issue/24301][proposal discussion issue]]. +Please point out problems on the [proposal discussion issue](https://golang.org/issue/24301). I will keep the -[[https://golang.org/issue/24301#issuecomment-371228742][discussion summary]] +[discussion summary](https://golang.org/issue/24301#issuecomment-371228742) and -[[https://golang.org/issue/24301#issuecomment-371228664][FAQ]] +[FAQ](https://golang.org/issue/24301#issuecomment-371228664) updated as feedback arrives. For this proposal to succeed, the Go ecosystem as a @@ -284,6 +285,6 @@ If you are interested in participating in such a session, please email Steve Francia at spf@golang.org. We’re looking forward to (finally!) providing the Go community with a single, official answer -to the question of how to incorporate package versioning into `go`get`. +to the question of how to incorporate package versioning into `go get`. Thanks to everyone who helped us get this far, and to everyone who will help us going forward. We hope that, with your help, we can ship something that Go developers will love. |