Skip to content

spec: RFC-001 contextual keywords (no soft-break for v1.2) - #71

Merged
trendvidia merged 1 commit into
mainfrom
m1-kickoff-doc
Jun 5, 2026
Merged

spec: RFC-001 contextual keywords (no soft-break for v1.2)#71
trendvidia merged 1 commit into
mainfrom
m1-kickoff-doc

Conversation

@trendvidia

Copy link
Copy Markdown
Owner

Summary

Amends RFC-001 to make type, function, and annotation contextual keywords — recognized only at the start of a top-level declaration; accepted as identifiers everywhere else. Removes the soft-break that the original v1.2 reservation would have introduced.

Also drops the spurious reservations of expression (only meaningful in annotation-parameter-type position) and this (only inside engine-language bodies, which protocompile captures opaquely). Reduces the touched-tokens count from 5 to 3.

Follow-up to #54 (RFC corpus) and #70 (M1 kickoff doc). Tracked by #55.

What surfaced this

The M1 implementation pre-flight surfaced oneof type { ... } in Google's Cloud DLP API schema (Apache 2.0, vendored at parser/testdata/largeproto.proto in protocompile, 8 occurrences). The pattern is common across production protobuf schemas in the wild, including Google's own gRPC APIs.

Hard-reserving the words would break wide swaths of real-world protobuf code. Contextual recognition preserves every v1.1 schema unchanged — the parser uses the file-scope production's lookahead to distinguish type Email = ... (keyword) from oneof type { ... } (identifier).

Pattern is well-precedented: Java 9 added module, requires, exports, opens, to, with as contextual keywords for the same reason.

What this PR changes

File Change
docs/RFC-001-schema-extensions.md §5.1 — contextual-keyword design + rationale; explicit non-reservation of expression and this
docs/draft-trendvidia-protowire-01.md Reserved Keywords section + appendix ABNF — contextual-keyword wording
STABILITY.md v1.2 schema-language section — "no source-level incompatibility introduced in v1.2"
CHANGELOG.md [Unreleased] entry — contextual-keyword note
docs/M1-kickoff-protocompile.md PR 1 scope adjusted to 3 keywords + a contextual-keyword grammar bridge; identifier-audit replaces soft-break-audit; estimate revised 1–2 days → 2–3 days

Backward compatibility

After this amendment, the wire and semantic compatibility statements simplify:

  • Wire format — unchanged (was already)
  • Source formatalso unchanged; no schemas need renaming for v1.2

The migration story moves from "rename any identifier that collides" to "nothing changes."

Test plan

  • Read pass — confirm contextual-keyword design is consistent across RFC, IETF, STABILITY, CHANGELOG, kickoff doc
  • Audit grep — confirm the proposed grammar bridge (RFC §5.1 + kickoff §"What changes" item 3) covers all _NAME name-binding positions in protocompile/parser/proto.y
  • Confirm no other open issue (Ratify RFC-001 #56Upstream buf/protocompile compatibility strategy #69) needs updating in light of the amendment

Amends RFC-001 to make `type`, `function`, and `annotation`
contextual keywords — recognized only at the start of a top-level
declaration; accepted as identifiers everywhere else. Removes the
soft-break that the original v1.2 reservation would have introduced.

Discovery driving the change: implementation pre-flight surfaced
`oneof type { ... }` in Google's Cloud DLP API schema (Apache 2.0,
vendored in protocompile/parser/testdata/largeproto.proto, 8
occurrences) and many production schemas. Hard-reserving the words
would break wide swaths of real-world protobuf code, including
Google's own APIs. Contextual keywords preserve every v1.1 schema
unchanged.

Also drops the spurious reservations of `expression` (only meaningful
in annotation-parameter-type position) and `this` (only inside
engine-language bodies, which protocompile captures opaquely). Reduces
the touched-tokens count from 5 to 3.

Pattern is well-precedented — Java 9 added `module`, `requires`,
`exports`, `opens`, `to`, `with` as contextual keywords for exactly
this reason.

Files:
- docs/RFC-001-schema-extensions.md  contextual-keyword design + rationale
- docs/draft-trendvidia-protowire-01.md  Reserved Keywords + ABNF appendix
- STABILITY.md                       no source-level incompatibility for v1.2
- CHANGELOG.md                       updated v1.2.0 notes
- docs/M1-kickoff-protocompile.md    PR 1 scope adjusted to 3 keywords +
                                     contextual-keyword grammar bridge;
                                     estimate revised 1-2 days -> 2-3 days

Bundled into this PR (was originally just the kickoff doc) because the
kickoff scope only makes sense after the amendment; reviewing them as
one is cleaner than two sequential PRs against an unmerged base.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant