Clarify: Compatibility wording in specification.md vs. TEMPLATE.md status model #5

New issue

Open

opened 2026-08-12 20:42:08 +02:00 by michael · 0 comments

michael commented

2026-08-12 20:42:08 +02:00

Owner

Goal

Clarify whether the per-contract "Compatibility" paragraphs in
specification.md (daw_error/v1, daw_event/v1, daw_event_response/v1,
possibly others) are consistent with the draft -> beta -> stable
lifecycle model defined in TEMPLATE.md, and resolve any discrepancy.

Background

While updating daw_error/v1 and daw_event/v1 in this session, their
individual specification.md files were found to contain wording like:

"v1 is fixed once published. A backward-incompatible change requires
v2."

TEMPLATE.md's actual status model is more differentiated:

draft: changes possible at any time, without prior notice
beta: changes still possible, but must not happen silently: a
CHANGELOG.md entry is required
stable: no further changes within this version; a breaking change
becomes a new version

Both contracts touched in this session were (correctly, per
TEMPLATE.md's promotion criteria) still status: draft, so no v1/v2
conflict actually arose. But the specification.md wording reads as if
"published" already meant permanently frozen, which is stricter than
what TEMPLATE.md defines for draft/beta.

This may be intentional (a deliberate stricter rule some contracts
adopt beyond the baseline TEMPLATE.md model), or it may be leftover
wording from before the three-stage status model existed. This was
explicitly not resolved or changed during this session -- it needs its
own review, not an opportunistic fix bundled into unrelated contract
changes.

Scope

Review the Compatibility section of every contract's
specification.md against TEMPLATE.md's status model.
Decide, per contract or globally: does "Compatibility" describe the
same three-stage model, a deliberately stricter rule, or is the
wording simply outdated?
If outdated: align wording with TEMPLATE.md's actual model.
If deliberately stricter: state why in the contract's own
specification.md (or rationale.md, if the contract has one), so a
future reader does not assume it is inconsistent with TEMPLATE.md.

Acceptance criteria

Every contract's Compatibility section checked against
TEMPLATE.md
Discrepancies either fixed or explicitly justified as intentional
No contract's actual draft/beta/stable status changed as a side
effect of this review

References

DAW/daw-contracts TEMPLATE.md (status model, "Growth within a
version")
Discovered while updating daw_error/v1 and daw_event/v1

## Goal Clarify whether the per-contract "Compatibility" paragraphs in specification.md (daw_error/v1, daw_event/v1, daw_event_response/v1, possibly others) are consistent with the draft -> beta -> stable lifecycle model defined in TEMPLATE.md, and resolve any discrepancy. ## Background While updating daw_error/v1 and daw_event/v1 in this session, their individual specification.md files were found to contain wording like: "v1 is fixed once published. A backward-incompatible change requires v2." TEMPLATE.md's actual status model is more differentiated: - draft: changes possible at any time, without prior notice - beta: changes still possible, but must not happen silently: a CHANGELOG.md entry is required - stable: no further changes within this version; a breaking change becomes a new version Both contracts touched in this session were (correctly, per TEMPLATE.md's promotion criteria) still status: draft, so no v1/v2 conflict actually arose. But the specification.md wording reads as if "published" already meant permanently frozen, which is stricter than what TEMPLATE.md defines for draft/beta. This may be intentional (a deliberate stricter rule some contracts adopt beyond the baseline TEMPLATE.md model), or it may be leftover wording from before the three-stage status model existed. This was explicitly not resolved or changed during this session -- it needs its own review, not an opportunistic fix bundled into unrelated contract changes. ## Scope - Review the Compatibility section of every contract's specification.md against TEMPLATE.md's status model. - Decide, per contract or globally: does "Compatibility" describe the same three-stage model, a deliberately stricter rule, or is the wording simply outdated? - If outdated: align wording with TEMPLATE.md's actual model. - If deliberately stricter: state why in the contract's own specification.md (or rationale.md, if the contract has one), so a future reader does not assume it is inconsistent with TEMPLATE.md. ## Acceptance criteria - [ ] Every contract's Compatibility section checked against TEMPLATE.md - [ ] Discrepancies either fixed or explicitly justified as intentional - [ ] No contract's actual draft/beta/stable status changed as a side effect of this review ## References - DAW/daw-contracts TEMPLATE.md (status model, "Growth within a version") - Discovered while updating daw_error/v1 and daw_event/v1

michael added the

labels

2026-08-12 20:42:08 +02:00

michael referenced this issue from DAW/daw-modul-berhtjan-cli