Skip to content

[Language] Publish a per-construct stability and deprecation table #298

@cssbruno

Description

@cssbruno

Problem

The diagnostics registry already classifies each code by Stability
(stable / experimental / addon), but the language constructs themselves — blocks,
g: directives, metadata keywords, endpoint forms — have no published stability
or deprecation tier. The README warns that 0.x public contracts can still change,
yet a user or tooling author has no per-construct contract telling them which
parts are stable, experimental, deprecated, or planned.

Relevant code:

  • internal/diagnostics/registry.go: Stability precedent on diagnostic codes
  • internal/view/directives.go: supported and deferred g: directives
  • internal/lang/lexer.go, internal/lang/completion.go: keywords and blocks
  • docs/language/spec.md: prose deferrals scattered across sections

Scope

Define a per-construct stability tier (stable / experimental / deprecated /
planned) covering blocks, g: directives, metadata keywords, and endpoint
declaration forms. Publish it as a single table in the spec, align the
deferred-directive diagnostics with the tier, and optionally expose it through
existing tooling (gowdk explain / docs output).

Acceptance Criteria

  • A stability table covers every supported block, g: directive, and metadata
    keyword.
  • Deferred or unsupported constructs are listed as planned/deprecated together
    with the diagnostic code emitted when used.
  • docs/language/spec.md references the table as the per-construct contract.
  • Deferred-directive diagnostics and the table stay consistent (tested where a
    registry/table mapping exists).

Verification

go test ./internal/view ./internal/lang
# plus doc review of docs/language/spec.md

Metadata

Metadata

Assignees

No one assigned

    Labels

    docsDocumentation workparser.gwdk parser and syntax handling

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions