Go.dev connects package documentation to module versions

Package documentation becomes less useful when it describes code other than the version a program actually builds. Go's move to explicit module versions makes that mismatch harder to ignore. A package search service needs to help identify the version being evaluated, alongside the exported operations it documents.

Steve Francia and Julie Qiu's November 13 launch announcement introduces go.dev and the package experience at pkg.go.dev. The package site understands modules and provides information about all versions of a package, including releases of the standard library. That is the most concrete engineering change behind the new developer hub.

The announcement also identifies broader questions heard from users over the preceding two years. They want to know who uses Go, what they use it for and how to find useful packages. The new hub combines learning material and use cases with package discovery, while leaving the open-source project and distribution at golang.org as of this launch.

I care about documentation that lets another engineer enter a codebase without first reconstructing its author's assumptions. Version-aware package information supports the same goal across dependency boundaries. The reader needs to know which contract belongs to the code being considered.

A package belongs to a versioned module

The March modules introduction defines a module as a set of packages under a root go.mod file. Its path contributes to the import paths of packages beneath that root, and its requirements specify other modules needed for a build. Package discovery therefore has to account for a larger unit of versioning than an isolated directory.

For example, the guide uses example.com/hello as a module path and explains that a world subdirectory has the import path example.com/hello/world. Those two package locations do not require separate modules. A package page can be useful in isolation, but evaluating its dependency role also requires recognizing the containing module.

This matters when reading documentation for a symbol found through search. Finding an operation with the desired name does not establish which module version supplies it. Nor does it establish that the consuming program selects that version. The new site's explicit version information gives the reader a way to ask those questions using the same model as the build tool.

The launch announcement says the new service serves documentation like godoc.org, with module understanding added. It also includes information about standard library releases. That extends the version question beyond third-party modules, because a program's toolchain determines which standard library implementation and declarations it receives.

Major versions alter the import contract

The modules guide gives a useful example of why a search result's package name is insufficient. A program can use both rsc.io/quote and rsc.io/quote/v3 during a gradual migration. Starting at v2, a module's major version appears in its module path under the semantic import versioning convention described there.

The new path identifies an incompatible version separately. It allows both major versions to appear in one build while the program changes its callers. The guide also makes clear that a build selects at most one version of any single module path. Version identity and import identity therefore interact in specific ways.

A documentation service that understands those identities can present a package in the context of the version being investigated. The announcement establishes that version information is available. It does not establish every possible migration aid, so the benefit should be stated at that level rather than assuming automated API-difference analysis or compatibility proofs.

For a reader considering a major upgrade, the practical question is whether an operation belongs to the existing import path or a new one. The March example even changes an exported function name during its major-version migration. Reading only a current-looking declaration without its module context could leave the reader planning a source change against the wrong dependency.

Search and licenses support an evaluation decision

The launch article says pkg.go.dev has an improved search algorithm and detects and displays licenses. These are useful capabilities, but the announcement supplies no benchmark for search quality or guarantee that a detected license settles every usage question. The concrete result is more information available during package discovery.

License information belongs near technical documentation because deciding to import a package is also deciding to rely on code distributed under particular terms. The modules tutorial explicitly describes correctness, security and licensing as costs to consider when adding dependencies. Ease of downloading does not eliminate those considerations.

Search addresses the preceding problem of finding a candidate at all. A package with a suitable operation is useful only if an engineer can discover it and identify the relevant version. Bringing discovery and documentation together reduces the need to reconstruct this context from unrelated search results and repository pages.

I see this as support for a dependency decision, with responsibility still resting on the engineer making it. Search ranking cannot demonstrate that a package fits a system's requirements. Documentation and a detected license can provide evidence that makes the decision more specific and reviewable.

The module services explain the wider direction

The August module services launch provides context for the new discovery experience. Its mirror retrieves and retains versioned module inputs. A checksum database provides a shared, auditable record of their contents, while the module index publishes a feed of new versions that become available through the mirror.

That index is useful to tools maintaining their own caches or following newly available modules. It reduces the need for every service to discover the same module versions independently. The launch announcement does not detail exactly how the new package site consumes those services, so the connection here is architectural context rather than a claim about its internal request flow.

Russ Cox's December 2018 module plan had already identified discovery as a consequence of decentralized hosting. Sites otherwise needed their own crawling mechanisms or had to wait until a user requested a package. A shared index was intended to make such services easier to build while preserving decentralized publication.

That distinction matters. Go modules can remain hosted under independently controlled paths while shared services help consumers find and retrieve them. A central documentation experience does not, by itself, require authors to publish all source code through a single registry or surrender control of their package names.

Documentation and authentication answer different questions

The checksum service's guarantee concerns consistent contents for a module version. Documentation concerns understanding those contents and the package's declared behavior. A checksum match does not establish good API design, and a well-written package page cannot authenticate a downloaded archive.

Keeping those responsibilities separate gives the new tools a useful place in a review. An engineer can find a candidate, inspect the relevant version's documentation and license information, then rely on the module mechanism to identify the code downloaded for that version. Each stage supplies evidence that the other stages cannot replace.

Standard library version information has a similar role. A documented declaration can explain what a particular Go release offers, while inspecting the executable or build configuration establishes which release the program uses. The package site's coverage of standard library releases makes the first part available without resolving the second automatically.

The module tutorial illustrates this separation with go list -m all, which lists the main module and its dependencies. That command reports the build's module choices, while a documentation page explains declarations within the chosen package. Using the selected version as the starting point for reading documentation avoids assuming that a search result and a local build describe identical inputs. Both pieces of information are needed to connect the package's documented behavior to the program.

The launch is deliberately limited

Francia and Qiu describe today's release as a minimum viable product and ask for feedback through the site's links. That limits what should be inferred from the announcement. The launch establishes the hub and its named capabilities, with expansion intended over time but no basis for describing unannounced functions as available now.

For engineers already comfortable with Go, the version information is sufficient reason to examine the package experience. A dependency choice concerns a particular set of declarations in a particular module release, and the new site can present those versions alongside documentation. That makes the page more useful when the question is whether the package actually belongs in the program being built.