Sub-issue of #639 — surface 3 of 3 ("What flows where"), automatic path. Stretch.
Depends on #674 for the extraction carrier and on #675 for the deprecation fragment type.
Scope
Detect when a deprecation is introduced, so nobody has to remember to write the fragment.
A codegen deprecation-manifest target emits a small structured list of every deprecated element — field path or model name, plus its message. Think of it as a generation target simpler than the Markdown reference: same extraction input, a summary instead of a document.
Run in diff mode against the last released tag, the target compares that manifest to the current one and emits each newly-appeared entry directly as a deprecation fragment. Detection and scaffolding fold into the one target, and the fragment body is the message already authored on the annotation — nothing is written twice.
Open questions
- Is manifest-plus-diff the right mechanism, or does a simpler check over the diff of the models themselves do the job?
- Where does diff mode run — a release-time tool, or a CI check on every PR that fails when a new deprecation ships without a fragment? The second catches the omission when it is cheap to fix.
- What is the manifest's stable identity for a field, given fields move between models? A qualified path is the obvious answer and needs confirming against the union/arm cases.
Acceptance
- The manifest target emits one entry per deprecated field and model, with its message.
- Diff mode against a tag with no deprecations emits a fragment per deprecated element; against the current HEAD it emits nothing.
- A deprecation removed between releases does not emit a fragment.
Integration points
Sub-issue of #639 — surface 3 of 3 ("What flows where"), automatic path. Stretch.
Depends on #674 for the extraction carrier and on #675 for the
deprecationfragment type.Scope
Detect when a deprecation is introduced, so nobody has to remember to write the fragment.
A codegen deprecation-manifest target emits a small structured list of every deprecated element — field path or model name, plus its message. Think of it as a generation target simpler than the Markdown reference: same extraction input, a summary instead of a document.
Run in diff mode against the last released tag, the target compares that manifest to the current one and emits each newly-appeared entry directly as a
deprecationfragment. Detection and scaffolding fold into the one target, and the fragment body is the message already authored on the annotation — nothing is written twice.Open questions
Acceptance
Integration points
markdown, reading the sameFieldSpec.deprecated/ model-spec carrier from [FEATURE] Carry deprecation through extraction and render it in the Markdown reference #674.changelog.d/as<pr>.deprecation.md.