docs: correct contributor prerequisites and stale dev-env references - #1520
Merged
Conversation
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>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
Go 1.24.xgo 1.26in go.modgolangci-lint v2.4.0v2.11.4pinned in ci.yml:30Rather than swap in fresher numbers — which only resets the clock on the same drift — this removes the numbers and names the authoritative file:
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.modhas notoolchaindirective, so under the defaultGOTOOLCHAIN=autothe toolchain downloads the required version automatically. A contributor on an older Go gets an upgrade, not a failure — it only hard-errors underGOTOOLCHAIN=local. (An earlier version of this description said such a contributor "cannot build"; that was too strong.)goconstfindings incmd/publisher/commands/validate_test.gothat 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 checkdoes more than documentedDocumented 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 runningdev-composeenvironment. 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
cmd/registry/— the server entry point and ko/goreleaser build target — andinternal/importer/.tests/integration/README.mdsaid 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 callsGET /v0/serversandGET /v0/servers/{serverName}/versions/latest(main.go:210,255).scripts/mirror_data/README.mdpointed atinternal/database/migrations/008_separate_official_metadata.sql, which does not exist — that migration is009_, while008_isclean_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 (maxMigrationis at :30 not :24; the connection string at :23 not :17), and corrected the fetch URL from/v0.1/serversto the/v0/serversthe script actually requests..env.examplewas missingMCP_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.exampleas the reference.docker-compose.ymlsetMCP_REGISTRY_ENVIRONMENT, which nothing reads — noENVIRONMENTenv tag ininternal/config, and no other occurrence in the repo. Removed. (The Pulumi-sidemcp-registry:environmentkey is a separate, real thing and is untouched.)CHANGES.md— 0 bytes, untouched since the squashed history base, zero references anywhere.Verification
docker compose configvalidates.grepforGo 1.x/golangci-lint vXacross all.md/.mdxnow returns nothing outsidecomplete.md(which #1522 deletes). Both../../README.md#pre-requisiteslinks resolve and the anchor matches the real#### Pre-requisitesheading.🤖 Generated with Claude Code