Skip to content

docs: define the 1.x compatibility policy for catalog, behavior, and output changes - #321

Merged
Teakowa merged 1 commit into
mainfrom
docs/313-compatibility-policy
Sep 28, 2026
Merged

Teakowa merged 1 commit into
mainfrom
docs/313-compatibility-policy

Conversation

@e54-bot

@e54-bot e54-bot commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

Fixes #313

Summary

Records how catalog, parse/validation/emit, and API changes are versioned under 1.x, in docs/compatibility-facades.md, and links it from the semver section of docs/release.md.

Decisions (maintainer)

  • Removed ids. Catalog corrections of never-native ids (the feat(catalog)!: retire non-native ids forcePlayerHero, stopForcingHero, forceThrottle, stopChasingVariable, isFiringSecondaryFire #299 kind) are minor releases, and the parser rejects the id afterwards. Overwatch has never removed a native Workshop action or value, so no legacy-id support is added. If it happens, the release notes declare it a breaking behavior change and the maintainer decides then between a minor and a major release.
  • Release notes. GitHub Release notes come from --generate-notes, i.e. merged PR titles. Catalog updates use feat(catalog). Other changes to parse/validation/emit results use feat(<area>) with a ## Behavior change section in the PR body. fix is kept for patch-level changes. No tooling change is needed, because release-plz already derives a minor release from feat.

Review points

  • Patch is defined strictly: any change observable in Program, emitted text, validation results, or catalog content is minor. Most past fix(parser|emitter|catalog) PRs would be feat under this rule.
  • The acceptance criterion "the next release uses it" can only be checked on the release after this merges.

Verification

Documentation-only change; maintainer review is the completion check. git diff --check passes, and the new anchor link from release.md matches the heading.

@Teakowa
Teakowa merged commit afac13f into main Sep 28, 2026
@Teakowa
Teakowa deleted the docs/313-compatibility-policy branch September 28, 2026 07:52
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.

Define the 1.x compatibility policy for catalog, behavior, and output changes

2 participants