docs: the contributor guide asked for SQLite headers and a server you don't need - #149
Merged
Merged
Conversation
… don't need Four claims in the docs contradicted the source they describe: - contributing.md listed SQLite3 development libraries as a prerequisite. Stale since v1.0.0, which made the driver pure Go precisely so no build needs a C toolchain or those headers (#128). - It said `make test` runs "with CGO enabled (required for SQLite)". The Makefile has CGO_ENABLED=0, as do every workflow and pre-commit hook. - It said the compatibility tests require a running DevCloud instance. The devcloud_server fixture starts one itself, on a free port, against a temp data dir it removes afterwards. The three env vars that override that (DEVCLOUD_EXTERNAL, DEVCLOUD_BIN, DEVCLOUD_PORT) are now documented. - getting-started.md advertised a Next.js frontend on port 3000 under Docker Compose. The compose file has one service. That frontend now lives in a separate repository. Also fills three gaps against the same sources: a generated Make target table (clean, changelog and stats appeared in no doc), a pre-commit and golangci-lint section, and the two admin routes /devcloud/api/fidelity and /devcloud/api/unrouted, which exist in internal/admin/api.go and were documented nowhere.
4 of 5 tasks
skyoo2003
added a commit
that referenced
this pull request
Sep 6, 2026
…tale figures, a missing fragment (#150) * fix: a release dry run discarded the artifacts it exists to produce The Upload assets step ran when dry_run was not set. So it uploaded on a real release, where GoReleaser has already attached the same archives and checksums to the GitHub Release, and skipped the one path that publishes nothing and therefore has no other output. RELEASE.md has described the intended behaviour all along: a dry run "builds artifacts and uploads them to the run, but publishes nothing". The condition was inverted, so a maintainer validating a build before committing to a tag got a green run with nothing to inspect. * docs: the compatibility policy quoted five figures the code had outgrown 775 boto3 tests, 948 auto-crud operations, 4,496 hand-verified, 148 registered services of which 31 served nothing, and a 93/11 split of model-backed to hand-written services. The measured values are 1,144, 5,193, 4,497, 205 with 4 serving nothing, and 193/12. Nothing caught the drift because nothing reads the file. cmd/devcloud/coverage_test.go gates docs/coverage.md, README.md and docs/README.md against the live registry in both directions; this document is not in that set, and the Go tests that do cite it (internal/config/config_test.go, internal/admin/api_test.go) lock the guaranteed surface by hardcoding keys rather than by parsing prose. The figures now come from the gated page or from a measurement, not from a restatement. This matters more than a stale number usually would: the document ships inside the release archive, so the copy in devcloud_vX.Y.Z_linux_amd64.tar.gz describes the binary beside it. * chore: add the changelog fragment PR #149 shipped without Release notes come from Changie fragments, not commits, so a merged user-facing change with no fragment is a change that will not appear in the release. PR #149 corrected four false claims in the contributor and getting-started guides and added none. Found by the pre-flight review for v1.1.0. The existing checks cannot see this: RELEASE.md's checklist verifies that every fragment carries an issue number and that the unreleased directory is not empty, neither of which notices a change that never wrote one.
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.
Summary
Four statements in the docs contradicted the source files they describe — a prerequisite that stopped being true at v1.0.0, two claims about how the tests run, and a frontend that lives in another repository. All four are corrected against the source, plus three gaps filled from the same files.
Related Issue
Refs #128
Changes
Corrections — each verified against the file it describes:
contributing.md: SQLite3 development libraries listed as a prerequisite. Stale since v1.0.0, which made the driver pure Go precisely so that no build needs a C toolchain or SQLite headers (fix: released binaries could not start — swap SQLite driver to pure Go #128).docker/Dockerfile:7says as much in a comment. Removed, and replaced with a note on why nothing needs one.contributing.md: "make testruns all Go tests with CGO enabled (required for SQLite)".Makefile:8isCGO_ENABLED=0, as areci.yml,compat.yml,release.yml,smithy-sync.ymland every Go pre-commit hook. Corrected, with the reason it is 0 (it is the mode.goreleaser.yamlpublishes in).contributing.md: compatibility tests "require a running DevCloud instance". They do not — thedevcloud_serversession fixture (tests/compatibility/conftest.py:104) starts one viago runon a free port, against a temp data dir it removes afterwards. Corrected, and the three env vars that override that behaviour (DEVCLOUD_EXTERNAL,DEVCLOUD_BIN,DEVCLOUD_PORT) are now documented —DEVCLOUD_BINin particular is a large speedup and was discoverable only by reading the fixture.getting-started.md: Docker Compose "starts a Next.js dev server on port 3000 with hot-reload".docker/docker-compose.ymldeclares one service. The dashboard UI moved to a separate repository —getting-started.mdalready said so 50 lines further down. Rewritten to describe what the file actually starts, including that it runs a six-service subset viaDEVCLOUD_SERVICES.Gaps filled from the same sources:
Makefile, marked<!-- AUTO-GENERATED -->.clean,changelogandstatsappeared in no document..pre-commit-config.yamlwas undocumented, andgolangci-lintwas named in the rootCONTRIBUTING.mdand the PR checklist but never in the contributor guide — including the fact that pre-commit does not run it, so CI is the first place it fires.GET /devcloud/api/fidelityandGET /devcloud/api/unroutedin the admin API list. Both are registered ininternal/admin/api.go:42-43;getting-started.mdlisted only the other three.Files Changed
docs/contributing.mddocs/getting-started.mdNo source, test, or config files are touched.
Test Plan
Documentation only — nothing to execute. Each claim was checked against its source rather than reasoned about:
grep -rn 'os.Getenv' internal/ cmd/returns exactly the three documented inconfiguration.md— that table was already correct and is unchanged.commof every target in theMakefileagainst everymake <target>incontributing.md— no target is now undocumented.CGO.{0,12}enabl,brew install sqlite,Next.js,port 3000returns nothing stale. The remaining hits are inchanges/v0.1.0.mdandchanges/v1.0.0.md, which are historical release notes and correct as history.docs/configuration.mdwas reviewed againstinternal/config/config.goand needed no change.Checklist
golangci-lint run) — no Go files changed; pre-commit passed