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
-## Packages, modules, and versions
+
+### Versions
-## go.mod files
+
+### Major version suffixes
-### go.mod file format
+
+### Resolving a package to a module
+
+## `go.mod` files
+
+
+### `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
-### Privacy
+
+### Communicating with version control systems
+
+### Custom import paths
+
+
+
+
+### 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).