Skip to content

Document all unstable API features in README - #1094

Merged
pelletier merged 2 commits into
v2from
docs/unstable-api-list
Jul 6, 2026
Merged

pelletier merged 2 commits into
v2from
docs/unstable-api-list

Conversation

@pelletier

Copy link
Copy Markdown
Owner

The "Unstable API" section of the README only mentioned Parser, but the unstable package also exports the Marshaler/Unmarshaler interfaces (opt-in via Encoder.EnableMarshalerInterface / Decoder.EnableUnmarshalerInterface) and RawMessage. Users browsing the README could not discover them.

  • README: add subsections for the marshaling interfaces and RawMessage, with pkg.go.dev links, matching the existing style. The AST types (Node, Iterator, Kind, โ€ฆ) remain covered by the Parser entry.
  • AGENTS.md: add a documentation rule that the Unstable API list must cover every feature exported by the unstable package and be updated in the same change that adds, promotes, or removes one.

๐Ÿค– Generated with Claude Code

The Unstable API section only mentioned Parser, but the unstable
package also exports the Marshaler/Unmarshaler interfaces and
RawMessage, so users browsing the README could not discover them.
List them all, and add a note to AGENTS.md so the list stays in
sync when unstable features are added, promoted, or removed.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@pelletier pelletier added documentation doc Relating to documentation and removed documentation labels Jul 5, 2026
The coverage CI job compares total coverage of the PR against v2 and
fails on any decrease. Whether arrayCount's nil-map fast path executes
depends on decoder pooling: a decoder reused from the sync.Pool keeps
its arrayCounts map allocated across documents, so the branch is only
hit when an array table is decoded by a fresh decoder, which varies
with GC timing and test scheduling. This made the job flake (97.6% vs
97.7%) on PRs that do not touch any Go code.

Cover the nil-map paths of arrayCount, setArrayCount and
resetChildArrayCounts deterministically with a direct test on a fresh
decoder.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
@pelletier
pelletier merged commit 61cbe9e into v2 Jul 6, 2026
13 checks passed
@pelletier
pelletier deleted the docs/unstable-api-list branch July 6, 2026 23:15
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

doc Relating to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant