From b003539a167e266fe086fc5682d50f6463130648 Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Mon, 11 Nov 2019 18:27:49 -0500 Subject: [PATCH] doc: add sections for modules, packages, versions to module reference Updates #33637 Change-Id: I3a0d05551d5a680febf742b912a5a6e5af753a6e Reviewed-on: https://go-review.googlesource.com/c/go/+/206617 Run-TryBot: Jay Conrod TryBot-Result: Gobot Gobot Reviewed-by: Tyler Bui-Palsulich --- doc/modules.md | 72 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 72 insertions(+) diff --git a/doc/modules.md b/doc/modules.md index ac25eddcb5..dfaa791dca 100644 --- a/doc/modules.md +++ b/doc/modules.md @@ -13,9 +13,81 @@ this document to HTML before Go 1.14. --> ## Modules, packages, and versions +A [*module*](#glos-module) is a collection of packages that are released, +versioned, and distributed together. A module is identified by a [*module +path*](#glos-module-path), which is declared in a [`go.mod` +file](#go.mod-files), together with information about the module's +dependencies. The [*module root directory*](#glos-module-root-directory) is the +directory that contains the `go.mod` file. The [*main +module*](#glos-main-module) is the module containing the directory where the +`go` command is invoked. + +Each [*package*](#glos-package) within a module is a collection of source files +in the same directory that are compiled together. A [*package +path*](#glos-package-path) is the module path joined with the subdirectory +containing the package (relative to the module root). For example, the module +`"golang.org/x/net"` contains a package in the directory `"html"`. That +package's path is `"golang.org/x/net/html"`. + ### Versions +A [*version*](#glos-version) identifies an immutable snapshot of a module, which +may be either a [release](#glos-release-version) or a +[pre-release](#glos-pre-release-version). Each version starts with the letter +`v`, followed by a semantic version. See [Semantic Versioning +2.0.0](https://semver.org/spec/v2.0.0.html) for details on how versions are +formatted, interpreted, and compared. + +To summarize, a semantic version consists of three non-negative integers (the +major, minor, and patch versions, from left to right) separated by dots. The +patch version may be followed by an optional pre-release string starting with a +hyphen. The pre-release string or patch version may be followed by a build +metadata string starting with a plus. For example, `v0.0.0`, `v1.12.134`, +`v8.0.5-pre`, and `v2.0.9+meta` are valid versions. + +Each part of a version indicates whether the version is stable and whether it is +compatible with previous versions. + +* The [major version](#glos-major-version) must be incremented and the minor + and patch versions must be set to zero after a backwards incompatible change + is made to the module's public interface or documented functionality, for + example, after a package is removed. +* The [minor version](#glos-minor-version) must be incremented and the patch + version set to zero after a backwards compatible change, for example, after a + new function is added. +* The [patch version](#glos-patch-version) must be incremented after a change + that does not affect the module's public interface, such as a bug fix or + optimization. +* The pre-release suffix indicates a version is a + [pre-release](#glos-pre-release-version). Pre-release versions sort before + the corresponding release versions. For example, `v1.2.3-pre` comes before + `v1.2.3`. +* The build metadata suffix is ignored for the purpose of comparing versions. + Tags with build metadata are ignored in version control repositories, but + build metadata is preserved in versions specified in `go.mod` files. The + suffix `+incompatible` denotes a version released before migrating to modules + version major version 2 or later (see [Compatibility with non-module + repositories](#non-module-compat). + +A version is considered unstable if its major version is 0 or it has a +pre-release suffix. Unstable versions are not subject to compatibility +requirements. For example, `v0.2.0` may not be compatible with `v0.1.0`, and +`v1.5.0-beta` may not be compatible with `v1.5.0`. + +Go may access modules in version control systems using tags, branches, or +revisions that don't follow these conventions. However, within the main module, +the `go` command will automatically convert revision names that don't follow +this standard into canonical versions. The `go` command will also remove build +metadata suffixes (except for `+incompatible`) as part of this process. This may +result in a [*pseudo-version*](#glos-pseudo-version), a pre-release version that +encodes a revision identifier (such as a Git commit hash) and a timestamp from a +version control system. For example, the command `go get -d +golang.org/x/net@daa7c041` will convert the commit hash `daa7c041` into the +pseudo-version `v0.0.0-20191109021931-daa7c04131f5`. Canonical versions are +required outside the main module, and the `go` command will report an error if a +non-canonical version like `master` appears in a `go.mod` file. + ### Major version suffixes -- 2.50.0