Document the evolution principles in the README - #132
Conversation
Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>
🤖 Augment PR SummarySummary: This PR expands the README with an “Evolution” section explaining how the schema library is intended to evolve without breaking consumers. Changes:
Technical Notes: Emphasizes explicit version pinning to make downstream impact visible when new versions are introduced. 🤖 Was this summary useful? React with 👍 or 👎 |
| governing body publishes: edition years for ISO, IEEE, BIPM, and W3C | ||
| standards, RFC numbers for the IETF, dated releases for dated registries, | ||
| and in-place evolution for living registries. Self-published specifications | ||
| live under `other/`. |
There was a problem hiding this comment.
README.markdown:80 — This says self-published specs live under other/, but in the repo layout they appear under schemas/other/; consider clarifying whether paths here are relative to schemas/ to avoid confusion for readers browsing the tree.
Severity: low
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| live under `other/`. | ||
| - **Every schema is individually versioned**. Each concept lives at | ||
| `<concept>/v1.json` and there are no unversioned aliases. | ||
| - **Versions never change their validation behavior**. A published version |
There was a problem hiding this comment.
README.markdown:83-90 — The “Versions never change their validation behavior” bullet reads like a universal rule, but the next bullet says some “living registries drift in place,” which implies validation can change within a version; consider explicitly scoping the immutability guarantee (or noting the exception) so the principles don’t contradict.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
Signed-off-by: Juan Cruz Viotti jv@jviotti.com