Depos

Dependency notes for Go

go.mod records which modules a build requires and at which version. It does not record why a module was chosen, which of its APIs the code is built around, or what to run before moving it — and go get -u ./... moves everything at once.

Depos keeps a note for each module in .depos/go/DEPENDENCY-NOTES.md, beside go.mod, and shows it on the module's require line.

What Depos reads

  • Manifest: go.mod
  • Notes file: .depos/go/DEPENDENCY-NOTES.md
  • Section heading: the module path: ## github.com/spf13/cobra, ## github.com/jackc/pgx/v5

Depos reads module paths in require directives of go.mod, including // indirect ones, shown with their own scope. A tool directive points at the required module that provides it. replace, exclude, retract, go.work and vendor/ are not read as dependencies.

Depos never runs the go command, so it needs no Go toolchain.

Example

module example.com/billing

go 1.24

require (
    github.com/jackc/pgx/v5 v5.7.1
    github.com/spf13/cobra v1.8.1
    golang.org/x/sync v0.10.0 // indirect
)

.depos/go/DEPENDENCY-NOTES.md:

## github.com/jackc/pgx/v5

Postgres driver. Use it through internal/db only.

### Agent notes

- purpose: PostgreSQL driver and connection pool for the billing service
- usage: only through internal/db, which wraps the pool and the transaction helpers
- verify: `go test ./internal/db/...` against the Postgres in docker-compose.yml
- verified: v5.7.1

The heading is the module path as require spells it, major-version suffix included. A new major version of a Go module is a new module path, so moving from /v5 to /v6 starts a new section, and the old one stays with - status: removed <YYYY-MM> — <reason>.

Comments in go.mod

require (
    // pgx: use it through internal/db only
    github.com/jackc/pgx/v5 v5.7.1
    github.com/spf13/cobra v1.8.1 // CLI for the admin tools
)

A comment in go.mod starts with // and runs to the end of the line. /* */ is not allowed: the go command stops with mod files must use // comments.

The go command writes a comment of its own. // indirect marks a requirement that no package in the main module imports directly, and when go mod tidy marks a line that already has a comment, it puts indirect; in front of it: // indirect; CLI for the admin tools. When go mod tidy drops a requirement, the comments on its line and above it go with it.

Pinning a version

A require line is not a pin. It sets the lowest version the build accepts: when another module in the build requires a higher one, the build uses that, and in a module that says go 1.17 or later, go mod tidy rewrites the line to it. A comment beside the line stays, and may now describe a version that is no longer there.

go get github.com/spf13/[email protected] moves a requirement up or down. exclude keeps one version out, and the build takes the next higher one instead; replace swaps a module for another version or a local directory. Both apply only in the main module's go.mod.

No directive sets an upper bound, and a comment such as // keep below v1.9.0 does not stop go get either. Write the limit in the module's note as constraint:: agents read it before they move the module.

For AI coding agents

An agent reads a module's section before it adds, upgrades or removes the module, runs what verify: says, and records the version it checked in verified:. See the rules agents follow.