| 1 | # đŸ¤– Review brief: the platform changelog, code |
| 2 | |
| 3 | You are the independent reviewer of a finished build. The author is |
| 4 | Claude. Do not edit any file. |
| 5 | |
| 6 | ## What to read |
| 7 | |
| 8 | 1. The spec, rev 2: `docs/superpowers/specs/2026-10-06-platform-changelog-design.md`, |
| 9 | and the earlier findings `CODEX-FINDINGS-CHANGELOG-1.md` (all four were |
| 10 | taken; check the fixes hold). |
| 11 | 2. The platform branch: `git diff origin/main...platform-changelog` in |
| 12 | `/home/paulca/amadan.net/carlos/platform-changelog`, excluding the |
| 13 | generated `docs/site/changelog.json` (read it as output, not code). |
| 14 | Code is `internal/changelog/`, `cmd/changelog/`, the `Line` and |
| 15 | `Parse` additions in `internal/docsite/docsite.go`, `docs/site/people.json`, |
| 16 | `docs/site/changelog-links.json`, and README step 10. |
| 17 | 3. The website: commit `59b9cf9` on branch `platform-changelog` in |
| 18 | `/home/paulca/github.com/carlosframework/website-changelog` |
| 19 | (`git show 59b9cf9 -- . ':!src/_data/docschangelog.json' ':!src/docs/cli.md'`). |
| 20 | `src/changelog.njk` renders the page; `hack/sync-docs.mjs` vendors |
| 21 | the data; `hack/check-docs.mjs` gates the build. |
| 22 | |
| 23 | ## Fixed: do not reopen |
| 24 | |
| 25 | The spec's four rulings; that change lines are verbatim records; that the |
| 26 | copy is in a separate human review (do not review wording). |
| 27 | |
| 28 | ## What to look for |
| 29 | |
| 30 | 1. **Wrong output on real history.** The generator has been run over all |
| 31 | 28 tags. Pick changes in `docs/site/changelog.json` and check them |
| 32 | against `git log` and `git for-each-ref refs/amadan/closed` (fetch |
| 33 | with `git fetch origin '+refs/amadan/closed/*:refs/amadan/closed/*'` |
| 34 | if missing): the range a release claims, the own commits a change |
| 35 | counts, credit, discussions, docs links. Name the commit. |
| 36 | 2. **Public safety.** Anything that could put an email address, a |
| 37 | private repo link or unescaped markup on the public page: the |
| 38 | generator, `CheckPublic`/`Redact`, the gate, and the template |
| 39 | (Nunjucks autoescape, the `notesMd` filters, `| safe`). |
| 40 | 3. **Gate holes.** A committed file that is wrong and still passes |
| 41 | `go test ./internal/changelog/` and `npm run check`. |
| 42 | 4. **Robustness at release time.** What breaks when the next release is |
| 43 | cut and step 10 is followed: a new tag, a new contributor, a bullet |
| 44 | with no bold lead, a release with no first-parent commits, gh or |
| 45 | amadan failing. |
| 46 | 5. **Code quality** where it would mislead the next person: dead code, |
| 47 | names that say the wrong thing, tests that pass for the wrong reason. |
| 48 | |
| 49 | Run `go test ./internal/changelog/ ./internal/docsite/` (set |
| 50 | `GOCACHE` to a writable directory) if you can; say if you could not. |
| 51 | |
| 52 | ## Output |
| 53 | |
| 54 | A numbered list, each with severity (P1 publishes something wrong or |
| 55 | breaks the page or gate; P2 misleading or fragile; P3 nit), file:line, |
| 56 | evidence, and a proposed fix. Then one line: accept, accept with fixes, |
| 57 | or reject. |
| 58 | |
amadan