Cleanup for 8.0.0: comment audit, drop unneeded files, restructure AGENTS.md#324
Merged
Conversation
- Comment audit across Sources: the codebase is well-tended (comments are overwhelmingly non-obvious why, external facts, gotchas, and @unchecked/ fatalError justifications). Cut one restatement comment on Duration.seconds. - Drop the duplicate LICENSE.md (older 2023 copy; keep the standard 2024 LICENSE) and repoint the README link. - Drop three unreferenced test fixtures: invalid.json, simple_array.json, simple_dictionary.json.
The roadmap was internal planning; for the release, CHANGELOG.md carries the user-facing history and serves as the v8 release notes. Drop docs/roadmap.md and remove AGENTS.md's stale Roadmap section + its '(roadmap #8)' reference, pointing release history at CHANGELOG.md. CHANGELOG left as-is — already accurate and release-notes-ready (covers the actor migration, typed bodies, error model, events, interceptors, cache lifecycle, and the statusCodeType/composedURL deltas).
3lvis
changed the title
Apply the AGENTS.md guidance from GitHub's 2,500-repo study (and peers): commands early, a scannable source map with purpose annotations, tight cross-file invariants instead of paragraph-heavy essays, a three-tier Always/Ask/Never boundaries block, and progressive disclosure — the deep rationale now lives in the (just-audited) code comments rather than being duplicated here. Notes it's a refinement layer over the parent AGENTS.md files; no persona (the walk-up doesn't use one).
3lvis
changed the title
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
1 participant
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.
Pre-release tidy. Behavior-preserving — full suite (180) green, build warning-free. All changes are comments, docs, or unused-file drops.
Comment audit (Sources/)
Trialed every comment. The codebase is well-tended — comments are overwhelmingly non-obvious why, external facts (RFC 3986 §3.4, the 255-byte filename cap,
Retry-Afterformats), gotchas, and@unchecked/fatalErrorjustifications. One cut: a restatement comment onDuration.seconds.Dropped files
docs/roadmap.md— internal planning doc;CHANGELOG.mdis now the user-facing history / v8 release-notes source. Removed AGENTS.md's stale Roadmap section +(roadmap #8)reference.LICENSE.md— duplicate ofLICENSE(older 2023 copy); README link repointed.invalid.json,simple_array.json,simple_dictionary.json— test fixtures with zero references.Restructured AGENTS.md (best-practice guidelines)
Applied the guidance from GitHub's 2,500-repo study and peers: commands early, a scannable source map with purpose annotations, tight invariant bullets instead of 200–400-word essays, a three-tier Always/Ask/Never boundaries block, and progressive disclosure — deep rationale now lives in the (just-audited) code comments rather than being duplicated in the doc. No cargo-culted persona (the walk-up doesn't use one). The dense "Architecture (current)" essays → a file map + cross-file invariants.
CHANGELOG
Left as-is — already accurate and release-notes-ready; its
[8.0.0]section is the GitHub Release body at tag time.Tests
180 green, warning-free.