CINXE.COM

<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Proposal: Versioned Go Modules</title><link rel="stylesheet" type="text/css" href="/+static/base.css"/><link rel="stylesheet" type="text/css" href="/+static/doc.css"/><link rel="stylesheet" type="text/css" href="/+static/prettify/prettify.css"/></head><body class="Site"><header class="Site-header "><div class="Header"><div class="Header-title"></div></div></header><div class="Site-content Site-Content--markdown"><div class="Container"><div class="doc"><h1><a class="h" name="Proposal_Versioned-Go-Modules" href="#Proposal_Versioned-Go-Modules"><span></span></a><a class="h" name="proposal_versioned-go-modules" href="#proposal_versioned-go-modules"><span></span></a>Proposal: Versioned Go Modules</h1><p>Author: Russ Cox<br />Last Updated: March 20, 2018<br />Discussion: <a href="https://golang.org/issue/24301">https://golang.org/issue/24301</a></p><h2><a class="h" name="Abstract" href="#Abstract"><span></span></a><a class="h" name="abstract" href="#abstract"><span></span></a>Abstract</h2><p>We propose to add awareness of package versions to the Go toolchain, especially the <code class="code">go</code> command.</p><h2><a class="h" name="Background" href="#Background"><span></span></a><a class="h" name="background" href="#background"><span></span></a>Background</h2><p>The first half of the blog post <a href="https://research.swtch.com/vgo-intro">Go += Package Versioning</a> presents detailed background for this change. In short, it is long past time to add versions to the working vocabulary of both Go developers and our tools, and this proposal describes a way to do that.</p><p><a href="https://semver.org">Semantic versioning</a> is the name given to an established convention for assigning version numbers to projects. In its simplest form, a version number is MAJOR.MINOR.PATCH, where MAJOR, MINOR, and PATCH are decimal numbers. The syntax used in this proposal follows the widespread convention of adding a “v” prefix: vMAJOR.MINOR.PATCH. Incrementing MAJOR indicates an expected breaking change. Otherwise, a later version is expected to be backwards compatible with earlier versions within the same MAJOR version sequence. Incrementing MINOR indicates a significant change or new features. Incrementing PATCH is meant to be reserved for very small, very safe changes, such as small bug fixes or critical security patches.</p><p>The sequence of <a href="https://research.swtch.com/vgo">vgo-related blog posts</a> presents more detail about the proposal.</p><h2><a class="h" name="Proposal" href="#Proposal"><span></span></a><a class="h" name="proposal" href="#proposal"><span></span></a>Proposal</h2><p>I propose to add versioning to Go using the following approach.</p><ol><li><p>Introduce the concept of a <em>Go module</em>, which is a group of packages that share a common prefix, the <em>module path</em>, and are versioned together as a single unit. Most projects will adopt a workflow in which a version-control repository corresponds exactly to a single module. Larger projects may wish to adopt a workflow in which a version-control repository can hold multiple modules. Both workflows will be supported.</p></li><li><p>Assign version numbers to modules by tagging specific commits with <a href="https://semver.org">semantic versions</a> such as <code class="code">v1.2.0</code>. (See the <a href="https://research.swtch.com/vgo-module">Defining Go Modules</a> post for details, including how to tag multi-module repositories.)</p></li><li><p>Adopt <a href="https://research.swtch.com/vgo-import">semantic import versioning</a>, in which each major version has a distinct import path. Specifically, an import path contains a module path, a version number, and the the path to a specific package inside the module. If the major version is v0 or v1, then the version number element must be omitted; otherwise it must be included.</p><p>The packages imported as <code class="code">my/thing/sub/pkg</code>, <code class="code">my/thing/v2/sub/pkg</code>, and <code class="code">my/thing/v3/sub/pkg</code> come from major versions v1, v2, and v3 of the module <code class="code">my/thing</code>, but the build treats them simply as three different packages. A program that imports all three will have all three linked into the final binary, just as if they were <code class="code">my/red/pkg</code>, <code class="code">my/green/pkg</code>, and <code class="code">my/blue/pkg</code> or any other set of three different import paths.</p><p>Note that only the major version appears in the import path: <code class="code">my/thing/v1.2/sub/pkg</code> is not allowed.</p></li><li><p>Explicitly adopt the “import compatibility rule”:</p><blockquote><p><em>If an old package and a new package have the same import path,</em><br /><em>the new package must be backwards compatible with the old package.</em></p></blockquote><p>The Go project has encouraged this convention from the start of the project, but this proposal gives it more teeth: upgrades by package users will succeed or fail only to the extent that package authors follow the import compatibility rule.</p><p>The import compatibility rule only applies to tagged releases starting at v1.0.0. Prerelease (vX.Y.Z-anything) and v0.Y.Z versions need not follow compatibility with earlier versions, nor do they impose requirements on future versions. In contrast, tagging a commit vX.Y.Z for X ≥ 1 explicitly indicates “users can expect this module to be stable.”</p><p>In general, users should expect a module to follow the <a href="https://golang.org/doc/go1compat#expectations">Go 1 compatibility rules</a> once it reaches v1.0.0, unless the module's documentation clearly states exceptions.</p></li><li><p>Record each module‘s path and dependency requirements in a <a href="XXX"><code class="code">go.mod</code> file</a> stored in the root of the module’s file tree.</p></li><li><p>To decide which module versions to use in a given build, apply <a href="https://research.swtch.com/vgo-mvs">minimal version selection</a>: gather the transitive closure of all the listed requirements and then remove duplicates of a given major version of a module by keeping the maximum requested version, which is also the minimum version satisfying all listed requirements.</p><p>Minimal version selection has two critical properties. First, it is trivial to implement and understand. Second, it never chooses a module version not listed in some <code class="code">go.mod</code> file involved in the build: new versions are not incorporated simply because they have been published. The second property produces <a href="XXX">high-fidelity builds</a> and makes sure that upgrades only happen when developers request them, never unexpectedly.</p></li><li><p>Define a specific zip file structure as the “interchange format” for Go modules. The vast majority of developers will work directly with version control and never think much about these zip files, if at all, but having a single representation enables proxies, simplifies analysis sites like godoc.org or continuous integration, and likely enables more interesting tooling not yet envisioned.</p></li><li><p>Define a URL schema for fetching Go modules from proxies, used both for installing modules using custom domain names and also when the <code class="code">$GOPROXY</code> environment variable is set. The latter allows companies and individuals to send all module download requests through a proxy for security, availability, or other reasons.</p></li><li><p>Allow running the <code class="code">go</code> command in file trees outside GOPATH, provided there is a <code class="code">go.mod</code> in the current directory or a parent directory. That <code class="code">go.mod</code> file defines the mapping from file system to import path as well as the specific module versions used in the build. See the <a href="https://research.swtch.com/vgo-cmd">Versioned Go Commands</a> post for details.</p></li><li><p>Disallow use of <code class="code">vendor</code> directories, except in one limited use: a <code class="code">vendor</code> directory at the top of the file tree of the top-level module being built is still applied to the build, to continue to allow self-contained application repositories. (Ignoring other <code class="code">vendor</code> directories ensures that Go returns to builds in which each import path has the same meaning throughout the build and establishes that only one copy of a package with a given import path is used in a given build.)</p></li></ol><p>The “<a href="https://research.swtch.com/vgo-tour">Tour of Versioned Go</a>” blog post demonstrates how most of this fits together to create a smooth user experience.</p><h2><a class="h" name="Rationale" href="#Rationale"><span></span></a><a class="h" name="rationale" href="#rationale"><span></span></a>Rationale</h2><p>Go has struggled with how to incorporate package versions since <code class="code">goinstall</code>, the predecessor to <code class="code">go get</code>, was released eight years ago. This proposal is the result of eight years of experience with <code class="code">goinstall</code> and <code class="code">go get</code>, careful examination of how other languages approach the versioning problem, and lessons learned from Dep, the experimental Go package management tool released in January 2017.</p><p>A few people have asked why we should add the concept of versions to our tools at all. Packages do have versions, whether the tools understand them or not. Adding explicit support for versions lets tools and developers communicate more clearly when specifying a program to be built, run, or analyzed.</p><p>At the start of the process that led to this proposal, almost two years ago, we all believed the answer would be to follow the package versioning approach exemplified by Ruby‘s Bundler and then Rust’s Cargo: tagged semantic versions, a hand-edited dependency constraint file known as a manifest, a machine-generated transitive dependency description known as a lock file, a version solver to compute a lock file satisfying the manifest, and repositories as the unit of versioning. Dep, the community effort led by Sam Boyer, follows this plan almost exactly and was originally intended to serve as the model for <code class="code">go</code> command integration. Dep has been a significant help for Go developers and a positive step for the Go ecosystem.</p><p>Early on, we talked about Dep simply becoming <code class="code">go dep</code>, serving as the prototype of <code class="code">go</code> command integration. However, the more I examined the details of the Bundler/Cargo/Dep approach and what they would mean for Go, especially built into the <code class="code">go</code> command, a few of the details seemed less and less a good fit. This proposal adjusts those details in the hope of shipping a system that is easier for developers to understand and to use.</p><h3><a class="h" name="Semantic-versions_constraints_and-solvers" href="#Semantic-versions_constraints_and-solvers"><span></span></a><a class="h" name="semantic-versions_constraints_and-solvers" href="#semantic-versions_constraints_and-solvers"><span></span></a>Semantic versions, constraints, and solvers</h3><p>Semantic versions are a reasonable convention for specifying software versions, and version control tags written as semantic versions have a clear meaning, but the <a href="https://semver.org/">semver spec</a> critically does not prescribe how to build a system using them. What tools should do with the version information? Dave Cheney‘s 2015 <a href="https://golang.org/issue/12302">proposal to adopt semantic versioning</a> was eventually closed exactly because, even though everyone agreed semantic versions seemed like a good idea, we didn’t know the answer to the question of what to do with them.</p><p>The Bundler/Cargo/Dep approach is one answer. Allow authors to specify arbitrary constraints on their dependencies. Build a given target by collecting all its dependencies recursively and finding a configuration satisfying all those constraints.</p><p>Unfortunately, the arbitrary constraints make finding a satisfying configuration very difficult. There may be many satisfying configurations, with no clear way to choose just one. For example, if the only two ways to build A are by using B 1 and C 2 or by using B 2 and C 1, which should be preferred, and how should developers remember? Or there may be no satisfying configuration. Also, it can be very difficult to tell whether there are many, one, or no satisfying configurations: allowing arbitrary constraints makes version solving problem an NP-complete problem, <a href="https://research.swtch.com/version-sat">equivalent to solving SAT</a>. In fact, most package managers now rely on SAT solvers to decide which packages to install. But the general problem remains: there may be many equally good configurations, with no clear way to choose between them, there may be a single best configuration, or there may be no good configurations, and it can be very expensive to determine which is the case in a given build.</p><p>This proposal's approach is a new answer, in which authors can specify only limited constraints on dependencies: only the minimum required versions. Like in Bundler/Cargo/Dep, this proposal builds a given target by collecting all dependencies recursively and then finding a configuration satisfying all constraints. However, unlike in Bundler/Cargo/Dep, the process of finding a satisfying configuration is trivial. As explained in the <a href="https://research.swtch.com/vgo-mvs">minimal version selection</a> post, a satisfying configuration always exists, and the set of satisfying configurations forms a lattice with a unique minimum. That unique minimum is the configuration that uses exactly the specified version of each module, resolving multiple constraints for a given module by selecting the maximum constraint, or equivalently the minimum version that satisfies all constraints. That configuration is trivial to compute and easy for developers to understand and predict.</p><h3><a class="h" name="Build-Control" href="#Build-Control"><span></span></a><a class="h" name="build-control" href="#build-control"><span></span></a>Build Control</h3><p>A module‘s dependencies must clearly be given some control over that module’s build. For example, if A uses dependency B, which uses a feature of dependency C introduced in C 1.5, B must be able to ensure that A's build uses C 1.5 or later.</p><p>At the same time, for builds to remain predictable and understandable, a build system cannot give dependencies arbitrary, fine-grained control over the top-level build. That leads to conflicts and surprises. For example, suppose B declares that it requires an even version of D, while C declares that it requires a prime version of D. D is frequently updated and is up to D 1.99. Using B or C in isolation, it‘s always possible to use a relatively recent version of D (D 1.98 or D 1.97, respectively). But when A uses both B and C, a SAT solver-based build silently selects the much older (and buggier) D 1.2 instead. To the extent that SAT solver-based build systems actually work, it is because dependencies don’t choose to exercise this level of control. But then why allow them that control in the first place?</p><p>Although the hypothetical about prime and even versions is clearly unlikely, real problems do arise. For example, issue <a href="https://github.com/kubernetes/client-go/issues/325">kubernetes/client-go#325</a> was filed in November 2017, complaining that the Kubernetes Go client pinned builds to a specific version of <code class="code">gopkg.in/yaml.v2</code> from September 2015, two years earlier. When a developer tried to use a new feature of that YAML library in a program that already used the Kubernetes Go client, even after attempting to upgrade to the latest possible version, code using the new feature failed to compile, because “latest” had been constrained by the Kubernetes requirement. In this case, the use of a two-year-old YAML library version may be entirely reasonable within the context of the Kubernetes code base, and clearly the Kubernetes authors should have complete control over their own builds, but that level of control does not make sense to extend to other developers' builds. The issue was closed after a change in February 2018 to update the specific YAML version pinned to one from July 2017. But the issue is not really “fixed”: Kubernetes still pins a specific, increasingly old version of the YAML library. The fundamental problem is that the build system allows the Kubernetes Go client to do this at all, at least when used as a dependency in a larger build.</p><p>This proposal aims to balance allowing dependencies enough control to ensure a successful build with not allowing them so much control that they break the build. Minimum requirements combine without conflict, so it is feasible (even easy) to gather them from all dependencies, and they make it impossible to pin older versions, as Kubernetes does. Minimal version selection gives the top-level module in the build additional control, allowing it to exclude specific module versions or replace others with different code, but those exclusions and replacements only apply when found in the top-level module, not when the module is a dependency in a larger build.</p><p>A module author is therefore in complete control of that module‘s build when it is the main program being built, but not in complete control of other users’ builds that depend on the module. I believe this distinction will make this proposal scale to much larger, more distributed code bases than the Bundler/Cargo/Dep approach.</p><h3><a class="h" name="Ecosystem-Fragmentation" href="#Ecosystem-Fragmentation"><span></span></a><a class="h" name="ecosystem-fragmentation" href="#ecosystem-fragmentation"><span></span></a>Ecosystem Fragmentation</h3><p>Allowing all modules involved in a build to impose arbitrary constraints on the surrounding build harms not just that build but the entire language ecosystem. If the author of popular package P finds that dependency D 1.5 has introduced a change that makes P no longer work, other systems encourage the author of P to issue a new version that explicitly declares it needs D < 1.5. Suppose also that popular package Q is eager to take advantage of a new feature in D 1.5 and issues a new version that explicitly declares it needs D ≥ 1.6. Now the ecosystem is divided, and programs must choose sides: are they P-using or Q-using? They cannot be both.</p><p>In contrast, being allowed to specify only a minimum required version for a dependency makes clear that P‘s author must either (1) release a new, fixed version of P; (2) contact D’s author to issue a fixed D 1.6 and then release a new P declaring a requirement on D 1.6 or later; or else (3) start using a fork of D 1.4 with a different import path. Note the difference between a new P that requires “D before 1.5” compared to “D 1.6 or later.” Both avoid D 1.5, but “D before 1.5” explains only which builds fail, while “D 1.6 or later” explains how to make a build succeed.</p><h3><a class="h" name="Semantic-Import-Versions" href="#Semantic-Import-Versions"><span></span></a><a class="h" name="semantic-import-versions" href="#semantic-import-versions"><span></span></a>Semantic Import Versions</h3><p>The example of ecosystem fragmentation in the previous section is worse when it involves major versions. Suppose the author of popular package P has used D 1.X as a dependency, and then popular package Q decides to update to D 2.X because it is a nicer API. If we adopt Dep's semantics, now the ecosystem is again divided, and programs must again choose sides: are they P-using (D 1.X-using) or Q-using (D 2.X-using)? They cannot be both. Worse, in this case, because D 1.X and D 2.X are different major versions with different APIs, it is completely reasonable for the author of P to continue to use D 1.X, which might even continue to be updated with features and bug fixes. That continued usage only prolongs the divide. The end result is that a widely-used package like D would in practice either be practically prohibited from issue version 2 or else split the ecosystem in half by doing so. Neither outcome is desirable.</p><p>Rust‘s Cargo makes a different choice from Dep. Cargo allows each package to specify whether a reference to D means D 1.X or D 2.X. Then, if needed, Cargo links both a D 1.X and a D 2.X into the final binary. This approach works better than Dep’s, but users can still get stuck. If P exposes D 1.X in its own API and Q exposes D 2.X in its own API, then a single client package C cannot use both P and Q, because it will not be able to refer to both D 1.X (when using P) and D 2.X (when using Q). The <a href="https://research.swtch.com/vgo-import">dependency story</a> in the semantic import versioning post presents an equivalent scenario in more detail. In that story, the base package manager starts out being like Dep, and the <code class="code">-fmultiverse</code> flag makes it more like Cargo.</p><p>If Cargo is one step away from Dep, semantic import versioning is two steps away. In addition to allowing different major versions to be used in a single build, semantic import versioning gives the different major versions different names, so that there's never any ambiguity about which is meant in a given program file. Making the import paths precise about the expected semantics of the thing being imported (is it v1 or v2?) eliminates the possibility of problems like those client C experienced in the previous example.</p><p>More generally, in semantic import versioning, an import of <code class="code">my/thing</code> asks for the semantics of v1.X of <code class="code">my/thing</code>. As long as <code class="code">my/thing</code> is following the import compatibility rule, that's a well-defined set of functionality, satisfied by the latest v1.X and possibly earlier ones (as constrained by <code class="code">go.mod</code>). Similarly, an import of <code class="code">my/thing/v2</code> asks for the semantics of v2.X of <code class="code">my/thing</code>, satisfied by the latest v2.X and possibly earlier ones (again constrained by <code class="code">go.mod</code>). The meaning of the imports is clear, to both people and tools, from reading only the Go source code, without reference to <code class="code">go.mod</code>. If instead we followed the Cargo approach, both imports would be <code class="code">my/thing</code>, and the meaning of that import would be ambiguous from the source code alone, resolved only by reading <code class="code">go.mod</code>.</p><p>Our article “<a href="https://golang.org/doc/articles/go_command.html">About the go command</a>” explains:</p><blockquote><p>An explicit goal for Go from the beginning was to be able to build Go code using only the information found in the source itself, not needing to write a makefile or one of the many modern replacements for makefiles. If Go needed a configuration file to explain how to build your program, then Go would have failed.</p></blockquote><p>It is an explicit goal of this proposal's design to preserve this property, to avoid making the general semantics of a Go source file change depending on the contents of <code class="code">go.mod</code>. With semantic import versioning, if <code class="code">go.mod</code> is deleted and recreated from scratch, the effect is only to possibly update to newer versions of imported packages, but still ones that are still expected to work, thanks to import compatibility. In contrast, if we take the Cargo approach, in which the <code class="code">go.mod</code> file must disambiguate between the arbitrarily different semantics of v1 and v2 of <code class="code">my/thing</code>, then <code class="code">go.mod</code> becomes a required configuration file, violating the original goal.</p><p>More generally, the main objection to adding <code class="code">/v2/</code> to import paths is that it‘s a bit longer, a bit ugly, and it makes explicit a semantically important detail that other systems abstract away, which in turn induces more work for authors, compared to other systems, when they change that detail. But all of these were true when we introduced <code class="code">goinstall</code>‘s URL-like import paths, and they’ve been a clear success. Before <code class="code">goinstall</code>, programmers wrote things like <code class="code">import "igo/set"</code>. To make that import work, you had to know to first check out <code class="code">github.com/jacobsa/igo</code> into <code class="code">$GOPATH/src/igo</code>. The abbreviated paths had the benefit that if you preferred a different version of <code class="code">igo</code>, you could check your variant into <code class="code">$GOPATH/src/igo</code> instead, without updating any imports. But the abbreviated imports also had the very real drawbacks that a build trying to use both <code class="code">igo/set</code> variants could not, and also that the Go source code did not record anywhere exactly which <code class="code">igo/set</code> it meant. When <code class="code">goinstall</code> introduced <code class="code">import "github.com/jacobsa/igo/set"</code> instead, that made the imports a bit longer and a bit ugly, but it also made explicit a semantically important detail: exactly which <code class="code">igo/set</code> was meant. The longer paths created a little more work for authors compared to systems that stashed that information in a single configuration file. But eight years later, no one notices the longer import paths, we’ve stopped seeing them as ugly, and we now rely on the benefits of being explicit about exactly which package is meant by a given import. I expect that once <code class="code">/v2/</code> elements in import paths are common in Go source files, the same will happen: we will no longer notice the longer paths, we will stop seeing them as ugly, and we will rely on the benefits of being explicit about exactly which semantics are meant by a given import.</p><h3><a class="h" name="Update-Timing-High_Fidelity-Builds" href="#Update-Timing-High_Fidelity-Builds"><span></span></a><a class="h" name="update-timing-high_fidelity-builds" href="#update-timing-high_fidelity-builds"><span></span></a>Update Timing & High-Fidelity Builds</h3><p>In the Bundler/Cargo/Dep approach, the package manager always prefers to use the latest version of any dependency. These systems use the lock file to override that behavior, holding the updates back. But lock files only apply to whole-program builds, not to newly imported libraries. If you are working on module A, and you add a new requirement on module B, which in turn requires module C, these systems will fetch the latest of B and then also the latest of C. In contrast, this proposal still fetches the latest of B (because it is what you are adding to the project explicitly, and the default is to take the latest of explicit additions) but then prefers to use the exact version of C that B requires. Although newer versions of C should work, it is safest to use the one that B did. Of course, if the build has a different reason to use a newer version of C, it can do that. For example, if A also imports D, which requires a newer C, then the build should and will use that newer version. But in the absence of such an overriding requirement, minimal version selection will build A using the exact version of C requested by B. If, later, a new version of B is released requesting a newer version of C, then when A updates to that newer B, C will be updated only to the version that the new B requires, not farther. The <a href="https://research.swtch.com/vgo-mvs">minimal version selection</a> blog post refers to this kind of build as a “high-fidelity build.”</p><p>Minimal version selection has the key property that a recently-published version of C is never used automatically. It is only used when a developer asks for it explicitly. For example, the developer of A could ask for all dependencies, including transitive dependencies, to be updated. Or, less directly, the developer of B could update C and release a new B, and then the developer of A could update B. But either way, some developer working on some package in the build must take an explicit action asking for C to be updated, and then the update does not take effect in A's build until a developer working on A updates some dependency leading to C. Waiting until an update is requested ensures that updates only happen when developers are ready to test them and deal with the possibility of breakage.</p><p>Many developers recoil at the idea that adding the latest B would not automatically also add the latest C, but if C was just released, there's no guarantee it works in this build. The more conservative position is to avoid using it until the user asks. For comparison, the Go 1.9 go command does not automatically start using Go 1.10 the day Go 1.10 is released. Instead, users are expected to update on their own schedule, so that they can control when they take on the risk of things breaking. The reasons not to update automatically to the latest Go release applies even more to individual packages: there are more of them, and most are not tested for backwards compatibility as extensively as Go releases are.</p><p>If a developer does want to update all dependencies to the latest version, that's easy: <code class="code">go get -u</code>. We may also add a <code class="code">go get -p</code> that updates all dependencies to their latest patch versions, so that C 1.2.3 might be updated to C 1.2.5 but not to C 1.3.0. If the Go community as a whole reserved patch versions only for very safe or security-critical changes, then that <code class="code">-p</code> behavior might be useful.</p><h2><a class="h" name="Compatibility" href="#Compatibility"><span></span></a><a class="h" name="compatibility" href="#compatibility"><span></span></a>Compatibility</h2><p>The work in this proposal is not constrained by the <a href="https://golang.org/doc/go1compat">compatibility guidelines</a> at all. Those guidelines apply to the language and standard library APIs, not tooling. Even so, compatibility more generally is a critical concern. It would be a serious mistake to deploy changes to the <code class="code">go</code> command in a way that breaks all existing Go code or splits the ecosystem into module-aware and non-module-aware packages. On the contrary, we must make the transition as smooth and seamless as possible.</p><p>Module-aware builds can import non-module-aware packages (those outside a tree with a <code class="code">go.mod</code> file) provided they are tagged with a v0 or v1 semantic version. They can also refer to any specific commit using a “pseudo-version” of the form v0.0.0-<em>yyyymmddhhmmss</em>-<em>commit</em>. The pseudo-version form allows referring to untagged commits as well as commits that are tagged with semantic versions at v2 or above but that do not follow the semantic import versioning convention.</p><p>Module-aware builds can also consume requirement information not just from <code class="code">go.mod</code> files but also from all known pre-existing version metadata files in the Go ecosystem: <code class="code">GLOCKFILE</code>, <code class="code">Godeps/Godeps.json</code>, <code class="code">Gopkg.lock</code>, <code class="code">dependencies.tsv</code>, <code class="code">glide.lock</code>, <code class="code">vendor.conf</code>, <code class="code">vendor.yml</code>, <code class="code">vendor/manifest</code>, and <code class="code">vendor/vendor.json</code>.</p><p>Existing tools like <code class="code">dep</code> should have no trouble consuming Go modules, simply ignoring the <code class="code">go.mod</code> file. It may also be helpful to add support to <code class="code">dep</code> to read <code class="code">go.mod</code> files in dependencies, so that <code class="code">dep</code> users are unaffected as their dependencies move from <code class="code">dep</code> to the new module support.</p><h2><a class="h" name="Implementation" href="#Implementation"><span></span></a><a class="h" name="implementation" href="#implementation"><span></span></a>Implementation</h2><p>A prototype of the proposal is implemented in a fork of the <code class="code">go</code> command called <code class="code">vgo</code>, available using <code class="code">go get -u golang.org/x/vgo</code>. We will refine this implementation during the Go 1.11 cycle and merge it back into <code class="code">cmd/go</code> in the main repository.</p><p>The plan, subject to proposal approval, is to release module support in Go 1.11 as an optional feature that may still change. The Go 1.11 release will give users a chance to use modules “for real” and provide critical feedback. Even though the details may change, future releases will be able to consume Go 1.11-compatible source trees. For example, Go 1.12 will understand how to consume the Go 1.11 <code class="code">go.mod</code> file syntax, even if by then the file syntax or even the file name has changed. In a later release (say, Go 1.12), we will declare the module support completed. In a later release (say, Go 1.13), we will end support for <code class="code">go</code> <code class="code">get</code> of non-modules. Support for working in GOPATH will continue indefinitely.</p><h2><a class="h" name="Open-issues-if-applicable" href="#Open-issues-if-applicable"><span></span></a><a class="h" name="open-issues-if-applicable" href="#open-issues-if-applicable"><span></span></a>Open issues (if applicable)</h2><p>We have not yet converted large, complex repositories to use modules. We intend to work with the Kubernetes team and others (perhaps CoreOS, Docker) to convert their use cases. It is possible those conversions will turn up reasons for adjustments to the proposal as described here.</p></div></div></div><footer class="Site-footer"><div class="Footer"><span class="Footer-poweredBy">Powered by <a href="https://gerrit.googlesource.com/gitiles/">Gitiles</a>| <a href="https://policies.google.com/privacy">Privacy</a>| <a href="https://policies.google.com/terms">Terms</a></span><div class="Footer-links"><a class="Footer-link" href="/proposal/+show/master/design/24301-versioned-go.md">source</a><a class="Footer-link" href="/proposal/+log/master/design/24301-versioned-go.md">log</a><a class="Footer-link" href="/proposal/+blame/master/design/24301-versioned-go.md">blame</a></div></div></footer></body></html>