Skip to content

docs: correct contributor prerequisites and stale dev-env references - #1520

Merged
rdimitrov merged 2 commits into
mainfrom
docs/contributor-prerequisites
Aug 10, 2026
Merged

docs: correct contributor prerequisites and stale dev-env references#1520
rdimitrov merged 2 commits into
mainfrom
docs/contributor-prerequisites

Conversation

@rdimitrov

@rdimitrov rdimitrov commented Aug 10, 2026

Copy link
Copy Markdown
Member

The README prerequisites were both stale, and the docs restated the Go version in three places.

Prerequisites: name the source, do not restate the version

README said Reality
Go 1.24.x go 1.26 in go.mod
golangci-lint v2.4.0 v2.11.4 pinned in ci.yml:30

Rather than swap in fresher numbers — which only resets the clock on the same drift — this removes the numbers and names the authoritative file:

- **Go** - version per the `go` directive in go.mod; the Go toolchain fetches it for you
- **golangci-lint** - version per the `golangci-lint-action` pin in ci.yml, so local lint matches CI

The Go version was stated in three places, which is exactly why all three drifted together. All three now point at a single source, so the prerequisites list cannot go stale.

Two notes on why the numbers earn so little in prose:

  • Go corrects itself. go.mod has no toolchain directive, so under the default GOTOOLCHAIN=auto the toolchain downloads the required version automatically. A contributor on an older Go gets an upgrade, not a failure — it only hard-errors under GOTOOLCHAIN=local. (An earlier version of this description said such a contributor "cannot build"; that was too strong.)
  • golangci-lint does not. Version skew here genuinely changes what you see: running CI's config under a newer golangci-lint (2.12.2) surfaces 23 goconst findings in cmd/publisher/commands/validate_test.go that CI's pinned 2.11.4 does not report. That is why the README now points at the pin rather than a number someone has to keep in sync.

make check does more than documented

Documented in three files as "lint, unit tests and integration tests". Actually check: dev-down lint validate test-all — it also runs schema validation and stops your running dev-compose environment. Worth knowing before running it mid-session. The Makefile's own ## help string already said this correctly; only the prose was stale.

Other verified corrections

  • README project structure omitted cmd/registry/ — the server entry point and ko/goreleaser build target — and internal/importer/.
  • tests/integration/README.md said the suite launches MongoDB. It launches PostgreSQL (postgres-integration-test), as the same file admits nine lines later. It also cited /v0/servers/{server_id}, a path removed a while ago; the test actually calls GET /v0/servers and GET /v0/servers/{serverName}/versions/latest (main.go:210,255).
  • scripts/mirror_data/README.md pointed at internal/database/migrations/008_separate_official_metadata.sql, which does not exist — that migration is 009_, while 008_ is clean_invalid_data.sql. (Migration 008's own header still calls itself "007a", which is how the numbering slipped.) Also swapped two "edit line NN" pointers for identifier names, since both had already drifted (maxMigration is at :30 not :24; the connection string at :23 not :17), and corrected the fetch URL from /v0.1/servers to the /v0/servers the script actually requests.
  • .env.example was missing MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION, even though the config reads it (config.go:18) and README:50 tells contributors to set it while pointing at .env.example as the reference.
  • docker-compose.yml set MCP_REGISTRY_ENVIRONMENT, which nothing reads — no ENVIRONMENT env tag in internal/config, and no other occurrence in the repo. Removed. (The Pulumi-side mcp-registry:environment key is a separate, real thing and is untouched.)
  • Deleted CHANGES.md — 0 bytes, untouched since the squashed history base, zero references anywhere.

Verification

docker compose config validates. grep for Go 1.x / golangci-lint vX across all .md/.mdx now returns nothing outside complete.md (which #1522 deletes). Both ../../README.md#pre-requisites links resolve and the anchor matches the real #### Pre-requisites heading.

🤖 Generated with Claude Code

rdimitrov and others added 2 commits August 10, 2026 15:57
The README prerequisites cannot produce a working setup:

- "Go 1.24.x" but both go.mod and deploy/go.mod declare `go 1.26`, so a
  contributor on 1.24 cannot build the module
- "golangci-lint v2.4.0" but CI pins v2.11.4, so local lint results do not
  match the lint that gates PRs

The Go version was stated in three places, which is why all three drifted
together. The two subordinate copies now point at the root README instead.

Other corrections, each verified against the code:

- `make check` is documented as "lint, unit tests and integration tests" in
  README, CONTRIBUTING and copilot-instructions. It is actually
  `dev-down lint validate test-all`, so it additionally runs schema validation
  and stops the contributor's running dev-compose environment. The Makefile's
  own help string already said this correctly.
- README project structure omitted `cmd/registry/` (the server entry point and
  ko/goreleaser build target) and `internal/importer/`
- tests/integration/README said the test suite launches MongoDB; it launches
  PostgreSQL (`postgres-integration-test`). It also cited
  `/v0/servers/{server_id}`, a path removed some time ago; the test actually
  calls `GET /v0/servers` and `GET /v0/servers/{serverName}/versions/latest`
- scripts/mirror_data/README referenced
  `internal/database/migrations/008_separate_official_metadata.sql`, which does
  not exist. That migration is `009_`; `008_` is `clean_invalid_data.sql`. Also
  replaced two brittle "edit line NN" pointers with the identifier names, since
  both line numbers had already drifted, and corrected the fetch URL from
  `/v0.1/servers` to the `/v0/servers` the script actually requests.
- .env.example was missing `MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION`, which the
  config reads and which the README tells contributors to set, while pointing
  at .env.example as the reference
- docker-compose.yml set `MCP_REGISTRY_ENVIRONMENT`, which no code reads; there
  is no `ENVIRONMENT` env tag in internal/config and no other reference in the
  repo
- Deleted CHANGES.md: 0 bytes, untouched since the history base, zero references

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Restating the versions is what made them stale in the first place, so replacing
one hardcoded number with a fresher hardcoded number just resets the clock.

This drops the numbers and names the authoritative file instead, which is the
same treatment already applied in this branch to tests/integration/README.md and
scripts/mirror_data/README.md. The prerequisites list can no longer drift.

Also worth noting: go.mod has no `toolchain` directive, so under the default
GOTOOLCHAIN=auto the Go toolchain downloads the required version itself. A
contributor on an older Go gets an automatic upgrade rather than a failure
(it only hard-errors under GOTOOLCHAIN=local), which is a further reason the
exact number does not belong in prose.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@rdimitrov
rdimitrov merged commit 3e463e5 into main Aug 10, 2026
6 checks passed
@rdimitrov
rdimitrov deleted the docs/contributor-prerequisites branch August 10, 2026 13:32
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant