From e0306c1d62d7d10e1e5239f51e01792b28e8001b Mon Sep 17 00:00:00 2001 From: Jay Conrod Date: Mon, 11 Nov 2019 18:19:04 -0500 Subject: [PATCH] doc: add glossary to module reference documentation These terms will be defined throughout the document, and more terms will be added. After drafting a few sections, it's clear that a glossary will be useful. There are enough terms that it would be overwhelming at the beginning. Also, add anchors for each heading and add a couple more headings. Updates #33637 Change-Id: I0017064f0b1e5e656dd280018ca0379484345df1 Reviewed-on: https://go-review.googlesource.com/c/go/+/206478 Run-TryBot: Jay Conrod TryBot-Result: Gobot Gobot Reviewed-by: Bryan C. Mills Reviewed-by: Tyler Bui-Palsulich --- doc/modules.md | 170 ++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 161 insertions(+), 9 deletions(-) diff --git a/doc/modules.md b/doc/modules.md index d9bc73efb3..ac25eddcb5 100644 --- a/doc/modules.md +++ b/doc/modules.md @@ -5,57 +5,209 @@ }--> - + + ## Introduction -## Glossary + +## Modules, packages, and versions + + +### Versions + + +### Major version suffixes -## Packages, modules, and versions + +### Resolving a package to a module -## go.mod files + +## `go.mod` files -### go.mod file format + +### `go.mod` file format + ### Minimal version selection (MVS) + ### Compatibility with non-module repositories + ## Module-aware build commands + ### Enabling modules + ### Initializing modules + ### Build commands + ### Vendoring + ### `go mod download` + ### `go mod verify` + ### `go mod edit` + ### `go clean -modcache` + ### Module commands outside a module + ## Retrieving modules + ### GOPROXY protocol -### Module zip requirements + +### Communicating with proxies + + +### Communicating with version control systems + + +### Custom import paths + + -### Privacy + +### File name and path constraints + +### Module zip format + + ### Private modules + ## Authenticating modules + ### go.sum file format + ### Checksum database -### Privacy + +## Privacy + + +## Environment variables + + +## Glossary + + +**build list:** The list of module versions that will be used for a build +command such as `go build`, `go list`, or `go test`. The build list is +determined from the [main module's](#glos-main-module) [`go.mod` +file](#glos-go.mod-file) and `go.mod` files in transitively required modules +using [minimal version selection](#glos-minimal-version-selection). The build +list contains versions for all modules in the [module +graph](#glos-module-graph), not just those relevant to a specific command. + + +**`go.mod` file:** The file that defines a module's path, requirements, and +other metadata. Appears in the [module's root +directory](#glos-module-root-directory). See the section on [`go.mod` +files](#go.mod-files). + + +**import path:** A string used to import a package in a Go source file. +Synonymous with [package path](#glos-package-path). + + +**main module:** The module in which the `go` command is invoked. + + +**major version:** The first number in a semantic version (`1` in `v1.2.3`). In +a release with incompatible changes, the major version must be incremented, and +the minor and patch versions must be set to 0. Semantic versions with major +version 0 are considered unstable. + + +**major version suffix:** A module path suffix that matches the major version +number. For example, `/v2` in `example.com/mod/v2`. Major version suffixes are +required at `v2.0.0` and later and are not allowed at earlier versions. See +the section on [Major version suffixes](#major-version-suffixes). + + +**minimal version selection (MVS):** The algorithm used to determine the +versions of all modules that will be used in a build. See the section on +[Minimal version selection](#minimal-version-selection) for details. + + +**minor version:** The second number in a semantic version (`2` in `v1.2.3`). In +a release with new, backwards compatible functionality, the minor version must +be incremented, and the patch version must be set to 0. + + +**module:** A collection of packages that are released, versioned, and +distributed together. + + +**module graph:** The directed graph of module requirements, rooted at the [main +module](#glos-main-module). Each vertex in the graph is a module; each edge is a +version from a `require` statement in a `go.mod` file (subject to `replace` and +`exclude` statements in the main module's `go.mod` file. + + +**module path:** A path that identifies a module and acts as a prefix for +package import paths within the module. For example, `"golang.org/x/net"`. + + +**module root directory:** The directory that contains the `go.mod` file that +defines a module. + + +**package:** A collection of source files in the same directory that are +compiled together. See the [Packages section](/ref/spec#Packages) in the Go +Language Specification. + + +**package path:** The path that uniquely identifies a package. A package path is +a [module path](#glos-module-path) joined with a subdirectory within the module. +For example `"golang.org/x/net/html"` is the package path for the package in the +module `"golang.org/x/net"` in the `"html"` subdirectory. Synonym of +[import path](#glos-import-path). + + +**patch version:** The third number in a semantic version (`3` in `v1.2.3`). In +a release with no changes to the module's public interface, the patch version +must be incremented. + + +**pre-release version:** A version with a dash followed by a series of +dot-separated identifiers immediately following the patch version, for example, +`v1.2.3-beta4`. Pre-release versions are considered unstable and are not +assumed to be compatible with other versions. A pre-release version sorts before +the corresponding release version: `v1.2.3-pre` comes before `v1.2.3`. See also +[release version](#glos-release-version). + + +**pseudo-version:** A version that encodes a revision identifier (such as a Git +commit hash) and a timestamp from a version control system. For example, +`v0.0.0-20191109021931-daa7c04131f5`. Used for [compatibility with non-module +repositories](#non-module-compat) and in other situations when a tagged +version is not available. + + +**release version:** A version without a pre-release suffix. For example, +`v1.2.3`, not `v1.2.3-pre`. See also [pre-release +version](#glos-pre-release-version). + + +**version:** An identifier for an immutable snapshot of a module, written as the +letter `v` followed by a semantic version. See the section on +[Versions](#versions). -- 2.50.0