Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
# Changelog

Each entry records a versioned change to a specification in this repository.
Each specification is versioned independently, starting at version 1. Every
pull request that alters normative content bumps the affected spec's `Version`
field and adds an entry here.
Each specification is versioned independently, starting at version 1.

Every pull request that alters normative content adds an entry here. The
version field is bumped per the standard rule (one PR, one bump) **unless**
the spec is in **Draft** status, in which case the
[draft-stage versioning rule](README.md#draft-stage-versioning) applies:
compatible changes fold into the current version; only incompatible features
bump.

## OVOS-INTENT-1 — Sentence Template Grammar

Expand Down
33 changes: 29 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -105,10 +105,10 @@ Specifications are **versioned documents, not living wikis**. Any
change to a spec — however small — **MUST** be submitted as a pull
request, never committed directly.

Each PR that alters normative content **MUST**:

- bump the spec's `Version` field in its header;
- add a corresponding entry to [CHANGELOG.md](CHANGELOG.md).
Each PR that alters normative content **MUST** add a
corresponding entry to [CHANGELOG.md](CHANGELOG.md) and, **unless
the draft-stage rule below applies**, bump the spec's `Version`
field in its header.

A version identifies an exact, citable state of a document, so
implementations and conformance results can name the version they
Expand All @@ -118,6 +118,31 @@ PRs that touch only the non-normative material —
[APPENDIX.md](APPENDIX.md), [GLOSSARY.md](GLOSSARY.md), this
README, examples — do not require a version bump.

### Draft-stage versioning

While a specification carries **Status: Draft**, the `Version`
field also doubles as a **compatibility signal** with current
OVOS:

- **v1** — drop-in compatible with current OVOS. A conforming
implementation runs against today's OVOS unchanged.
- **v2** — incompatible: requires OVOS-side changes (renamed
topics, new orchestrator responsibilities, payload-shape
changes, etc.).

PRs in draft therefore follow a refined rule:

- A PR that adds, refines, or loosens content **without** breaking
compatibility with current OVOS **MAY** keep the spec at its
current version (typically v1) and fold the change into that
version's CHANGELOG entry.
- A PR that introduces an incompatible feature **MUST** bump the
spec to v2 (or the next major).

The rule applies only while the spec is in **Draft** status; once
a spec is promoted out of Draft, every normative change bumps the
version per the standard rule above.

---

## Credits
Expand Down