Skip to content

CHANGELOG documents the annotations channel under [0.3.0], but it isn't in the spec/v0.3.0 release (or any client tag) #222

Description

@colbylwilliams

Summary

The ## [0.3.0] section of CHANGELOG.md on main documents an annotations
channel
as part of the 0.3.0 release:

  • Added a new annotations channel exposed on ahp-session:/<uuid>/annotations. …
  • Added an annotations MessageAttachment variant (MessageAnnotationsAttachment) …

But the annotations channel is not present in the spec/v0.3.0 release, nor in
any per-language client tagged at the same commit. It exists only on main
(unreleased). This isn't a per-client codegen lag — every client matches the spec
source at the tag; it's that two unreleased additions are documented under the
released [0.3.0] heading.

Evidence

  • spec/v0.3.0 and the client tags rust/v0.3.0, typescript/v0.3.0,
    kotlin/v0.3.0, clients/go/v0.3.0, and v0.3.0 (Swift) all resolve to the
    same commit and an identical tree.
  • At that commit, types/ contains no annotations sources (no
    types/channels-annotations/, no AnnotationsState, no annotations/*
    actions, no AnnotationsSummary / MessageAnnotationsAttachment). The
    generated clients therefore correctly don't contain them either.
  • The ## [0.3.0] section of CHANGELOG.md at the spec/v0.3.0 tag does
    not mention annotations. The two annotations bullets were added to the
    [0.3.0] section on main after the release was cut.
  • On main, annotations does exist (types/channels-annotations/…,
    types/test-cases/reducers/21x-annotations-*.json), confirming it is a real
    but post-0.3.0 addition.

Impact

A consumer that pins the released 0.3.0 of any client and reads the 0.3.0
changelog will expect an annotations channel
(annotations/set|removed|entrySet|entryRemoved, SessionSummary.annotations /
AnnotationsSummary, MessageAnnotationsAttachment) that isn't in the release.
There is no released protocol version that both reports PROTOCOL_VERSION
0.3.0 and includes annotations, which makes "target released 0.3.0" ambiguous
for downstream implementers.

Suggested resolution

Either (or both):

  1. Move the annotations entries (and any other main-only additions that slipped
    into a released section) out of [0.3.0] into [Unreleased] / the next
    version's section, so the released 0.3.0 changelog matches what spec/v0.3.0
    actually shipped.
  2. Cut a release (e.g. the next minor) that actually includes the annotations
    channel, so the documented surface is available to consumers pinning a tag.

Happy to send a PR for the changelog correction if that's the preferred fix.

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions