Launch readiness: the first release that asks strangers to adopt a port

[blairham]

Tracking issue for the first release that asks strangers to adopt this. Mirrors the process used for blairham/stevedore #25, with the differences that matter for a port: everything here has to survive the reader who already uses the thing we reimplemented.

The care a port needs

Three of these are not present anywhere in the repo today.

• Attribution. This repo is Apache-2.0 and reimplements two MIT projects (pre-commit, © 2014 Anthony Sottile & Ken Struys; identify, © 2017 Chris Kuehl & Anthony Sottile). There is no NOTICE, and no mention of either copyright anywhere in the tree. internal/identify/identify.go follows upstream identify's data tables closely enough that this is not optional.
• The name collision, stated up front. The binary is pre-commit and the tap formula is pre-commit; brew info already prints pre-commit shadows homebrew/core/pre-commit, and the README tells people to sudo mv pre-commit /usr/local/bin/ over the Python tool. Decision: keep both names — git hooks invoke pre-commit by name, so shadowing is the drop-in contract, not an accident. That makes documenting it a blocker rather than a nicety.
• The shared cache, stated up front. Default store is ~/.cache/pre-commit, same as Python, but the metadata format is not compatible (JSON + sha256 dir names vs sqlite + random names), and clean is RemoveAll over the whole directory. Decision: match upstream exactly, including the destructive clean. Same conclusion — document, don't diverge.

Honest state before we claim parity

• docs/parity.md — generated from test/integration/parity_report.json, not from memory. Current: 78 checks, 75 pass, 3 known differences.
• The committed report was generated against Python 4.5.0 while the version scheme claims 4.6 parity (upstream latest is 4.6.2). Regenerate against 4.6.x and pin the version the CI job installs — pip install pre-commit is unpinned today, so the number moves without a commit.
• The README claims 22 languages. Ten of them (conda, coursier, dart, dotnet, haskell, julia, lua, perl, r, swift) live in a single 279-line internal/languages/others.go with no test file and no coverage in the parity harness. Either cover them or grade the claim honestly in docs/parity.md.
• The parity job is gated on push or a test-languages label, so it does not run on most PRs.
• CI is ubuntu-latest only, but releases ship macOS and Windows archives. Windows in particular has never been exercised.

Adoption surface

• docs/comparison.md — "should I use this instead of Python pre-commit?", leading with the case for not switching.
• docs/stability.md — v4.6.x means upstream parity, not semver of this codebase. Without this, v4 reads as maturity and the first breaking change reads as a broken promise.
• docs/announcement.md — the launch playbook, written before anything is posted.
• README restructure: lead with the story, move the command reference into docs/, fix the Action example (pins @main, should be @v4).
• Community health files: CONTRIBUTING, CODE_OF_CONDUCT, SECURITY, issue templates.
• Repo metadata: description (empty today), topics (none, so the repo is invisible in GitHub search), homepage, Discussions, social preview.
• Publish the composite action to the GitHub Marketplace (manual: a checkbox on the release form).

Pre-flight

• brew install blairham/tap/pre-commit on a clean machine, with homebrew/core's pre-commit already installed — verify the failure mode is comprehensible.
• go install github.com/blairham/go-pre-commit/v4@latest then the rename step, exactly as the README describes it.
• uses: blairham/go-pre-commit@v4 resolves.
• Every command in the README quick start, in order, in a scratch repo.

[blairham]

Launch readiness: done, and what it turned up

Everything in this issue's engineering scope has landed, and v4.6.7 is released — the first release cut against this checklist.

Shipped

PR	What
#48	golangci-lint actually reports issues in CI (--new-from-merge-base)
#49	CONTRIBUTING, SECURITY, CODE_OF_CONDUCT, issue templates, PR template; fixed a dead evidence link in parity.md
#50	--files takes several paths, as upstream does
#51	A parity divergence now fails the job instead of only printing
#52	The action runs on macOS and Windows in CI; Windows arm64 archive now built
#54	docs/announcement.md — the launch playbook

Private vulnerability reporting is enabled, so SECURITY.md's instructions are true. Discussions were already on; description and topics were already set.

Three real defects, found because the checklist made us look

1. pre-commit run --files a b was broken in every release (#50). Upstream's --files is argparse nargs='*'; ours bound one value per occurrence, so the second path became a stray positional and the run died with expected at most 1 argument without touching a file. This is the ordinary way to scope a run — diff-scoped CI, xargs, editors.

2. The parity suite could not fail (#51). Every comparison was recorded and rendered, but nothing asserted on one — TestMain forced a non-zero exit only when zero checks ran. A divergence printed [FAIL], lowered the percentage, and exited 0. So the job this repo describes as failing "before review rather than after a merge to main" could not. That is how defect 1 shipped under a 78/78 headline.

Measured, on a tree with two genuine divergences: before → exit 0; after → exit 1; clean tree unchanged at exit 0. The suite is now 82/82.

3. Windows is broken, not merely untested (#53). The very first Windows CI run failed:

failed to install environment for hook "trailing-whitespace":
  pip install failed: exec: "...\py_env-default\bin\pip": executable file not found

Every language backend that installs an environment hardcodes bin; a Windows virtualenv uses Scripts. Scripts appears nowhere in the tree and runtime.GOOS is consulted only in docker.go, so python, node, ruby and golang hooks all fail there. The binary installs and runs, and pygrep/fail/system/script hooks work.

This was previously documented as "Windows has never been exercised by anyone; it builds, and that is the extent of what is known" — which reads as "probably fine". It is now stated precisely in docs/parity.md, docs/comparison.md and the README, and tracked in #53.

Also filed: #55 — go install builds report 4.6.0 regardless of the version installed, because internal/config.Version is a hardcoded literal that only the release ldflags overwrite.

The one remaining item is a UI click

• Publish the composite action to the GitHub Marketplace — a checkbox on the release form, with no API. Everything it requires is in place: public repo, single action.yml at root with name/description/branding, unique name, README, and a release to attach it to.

Closing this; #53 and #55 carry the follow-up work.