Skip to content

docs: the contributor guide asked for SQLite headers and a server you don't need - #149

Merged
skyoo2003 merged 1 commit into
mainfrom
docs/correct-contributor-guide
Sep 6, 2026
Merged

skyoo2003 merged 1 commit into
mainfrom
docs/correct-contributor-guide

Conversation

@skyoo2003

Copy link
Copy Markdown
Owner

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:7 says as much in a comment. Removed, and replaced with a note on why nothing needs one.
  • contributing.md: "make test runs all Go tests with CGO enabled (required for SQLite)". Makefile:8 is CGO_ENABLED=0, as are ci.yml, compat.yml, release.yml, smithy-sync.yml and every Go pre-commit hook. Corrected, with the reason it is 0 (it is the mode .goreleaser.yaml publishes in).
  • contributing.md: compatibility tests "require a running DevCloud instance". They do not — the devcloud_server session fixture (tests/compatibility/conftest.py:104) starts one via go run on 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_BIN in 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.yml declares one service. The dashboard UI moved to a separate repository — getting-started.md already said so 50 lines further down. Rewritten to describe what the file actually starts, including that it runs a six-service subset via DEVCLOUD_SERVICES.

Gaps filled from the same sources:

  • A Make target table generated from the Makefile, marked <!-- AUTO-GENERATED -->. clean, changelog and stats appeared in no document.
  • A pre-commit and linting section. .pre-commit-config.yaml was undocumented, and golangci-lint was named in the root CONTRIBUTING.md and 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/fidelity and GET /devcloud/api/unrouted in the admin API list. Both are registered in internal/admin/api.go:42-43; getting-started.md listed only the other three.

Files Changed

File Type Change
docs/contributing.md Modified 3 corrections, Make target table, pre-commit/lint section
docs/getting-started.md Modified Compose section rewritten, 2 admin routes added

No 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:

  • Env vars: grep -rn 'os.Getenv' internal/ cmd/ returns exactly the three documented in configuration.md — that table was already correct and is unchanged.
  • Make targets: comm of every target in the Makefile against every make <target> in contributing.md — no target is now undocumented.
  • Residual claims: a repo-wide grep for CGO.{0,12}enabl, brew install sqlite, Next.js, port 3000 returns nothing stale. The remaining hits are in changes/v0.1.0.md and changes/v1.0.0.md, which are historical release notes and correct as history.
  • Every relative link and heading anchor added here resolves.
  • Pre-commit passed on the commit.

docs/configuration.md was reviewed against internal/config/config.go and needed no change.

Checklist

  • Self-reviewed the code
  • Added/updated tests — N/A, documentation only
  • Lint/format passes (golangci-lint run) — no Go files changed; pre-commit passed
  • Updated documentation (if applicable) — this PR is the documentation update
  • Added a Changie changelog fragment for user-facing changes — N/A per the template, docs only

… 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.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 6, 2026
@skyoo2003
skyoo2003 merged commit 188e1e0 into main Sep 6, 2026
8 checks passed
@skyoo2003
skyoo2003 deleted the docs/correct-contributor-guide branch September 6, 2026 07:38
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.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant