Skip to content

Define compatibility policy for conversions to prior struct shapes #124

Description

@ben-ranford

Problem

The bounded declaration comparison in #58 accepts plain defined-struct field additions that preserve existing keyed fields and comparability. Consumers that convert to the former underlying struct shape can still stop compiling.

At PR #88 head 4372762e7e68457f3255eb19b43f43558f2a69ba, an isolated compiled fixture proved:

  • Baseline type Options struct { Name string }: struct { Name string }(api.Options{}) compiles.
  • Candidate adds Enabled bool: that conversion fails.
  • api.Options{Name: "ok"} compiles against both versions.
  • The current compiled release-baseline CLI exits 0 and reports status=compatible.

This is distinct from unkeyed literals and promoted selectors (#114). A source inventory alone cannot establish how downstream consumers depend on the old struct shape.

Scope and acceptance

  • Define and document the compatibility policy for exported struct shapes and conversions to anonymous or separately defined types.
  • Add consumer compilation fixtures for old-shape conversions, pointers, named types and keyed construction controls.
  • Identify when a changed exported struct is a documented shape contract and make the release gate reject prohibited additions to that contract.
  • Keep additive fields that satisfy the supported consumer contract available; do not silently replace the existing policy with unconditional acceptance or reject all additive fields without an explicit policy decision.
  • Preserve the existing anonymous-alias rejection, embedded-selector boundary, comparability checks and unkeyed-literal warning.
  • Require explicit compatibility review and affected consumer compilation evidence for current field additions; passing declaration comparison alone is insufficient.
  • No new root dependency or minimum-Go increase.

Backlog follow-up outside the v1.1.0 implementation milestone. This issue records an unsupported consumer shape; it does not waive a known breaking change to a promised v1 consumer contract.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions