Tagging and Publishing

## The path is the identity and the address The `module` line in `go.mod` does double duty. It is the **name** — the prefix of every import path in the module — and it is the **address**, because the go command has no registry to ask and must derive a repository location from the path itself. Those two roles have to agree, and the toolchain enforces the agreement rather than trusting it. ### How a path becomes a repository Given `import github.com/acme/logkit/logfmt`, the go command does not know where the module boundary is, so it tries successively shorter prefixes until one resolves to a module: `github.com/acme/logkit/logfmt`, then `github.com/acme/logkit`, and so on. For the well-known code hosts the mapping is built in — the first two path elements after the host are the repository. For any other domain, the go command makes an HTTPS request to `https://<path>?go-get=1` and looks for an HTML meta tag: ```html <meta name="go-import" content="example.com/logkit git https://github.com/acme/logkit"> ``` That is the vanity-import mechanism: the import path is a name you control, and the meta tag says where the code actually lives. It is why a module can be imported as `example.com/logkit` while being hosted anywhere. ### The check on the way back Resolution gets bytes. The go command then opens the fetched `go.mod` and compares its `module` line with the path that was requested. Disagreement is a hard error: ``` go: example.com/[email protected]: parsing go.mod: module declares its path as: github.com/acme/logkit but was required as: example.com/logkit ``` The check matters because content can arrive through a mirror or a cache rather than straight from the repository. Verifying the declared path means the module cannot be silently served under someone else's name, and it means the same import path always denotes the same module regardless of the route the bytes took. ### The consequences maintainers actually feel **Renaming the repository renames the module.** If `github.com/acme/logkit` becomes `github.com/acme/logging`, the old import path no longer names your module. Even where the host issues an HTTP redirect and the fetch follows it, the `go.mod` at the other end now declares the new path, and consumers get the mismatch error. A rename is therefore a coordinated change: update the `module` line, update every internal import, tag a new version, and every consumer edits their imports. Treat it as publishing a different module, because that is what it is. **Moving a module to a subdirectory renames it too**, since the path includes the directory prefix under the repository root. **A private repository is a permissions problem, not a path problem.** The path still resolves; the fetch is what fails. The declared-path error and an authentication error look nothing alike, which is a useful diagnostic split. **The path must be a real, resolvable domain.** Inventing `module mycompany/tools` or `module logkit` produces something no consumer can fetch, and the failure only appears when a second team tries to import it. It is fine for a program nobody imports; it is a bug the moment the module is published. ### Choosing the path deliberately Because the path is baked into every consumer's imports, it is close to unchangeable once published. A vanity domain (`go.acme.dev/logkit`) buys the freedom to move hosts later without touching a single consumer import, at the cost of running a small static site that must stay up for as long as the module is used — a real operational commitment, since the go command consults it on a cold fetch. Using the host path directly costs nothing and ties you to that host's URL forever. Either is defensible; deciding after publication is not.