Skip to content

Document the evolution principles in the README - #132

Merged
jviotti merged 1 commit into
mainfrom
evolution-docs
Aug 5, 2026
Merged

Document the evolution principles in the README#132
jviotti merged 1 commit into
mainfrom
evolution-docs

Conversation

@jviotti

@jviotti jviotti commented Aug 5, 2026

Copy link
Copy Markdown
Member

Signed-off-by: Juan Cruz Viotti jv@jviotti.com

Review in cubic

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>
@jviotti
jviotti merged commit 0b70d9c into main Aug 5, 2026
3 checks passed
@jviotti
jviotti deleted the evolution-docs branch August 5, 2026 13:19
@augmentcode

augmentcode Bot commented Aug 5, 2026

Copy link
Copy Markdown
🤖 Augment PR Summary

Summary: This PR expands the README with an “Evolution” section explaining how the schema library is intended to evolve without breaking consumers.

Changes:

  • Documents how schema collection paths map to upstream authorities (ISO/IETF/W3C/etc.)
  • Explains per-concept versioning (e.g., v1.json) and explicit deprecation/supersession
  • Describes expectations around validation stability, linked-data identifiers, and generation sources

Technical Notes: Emphasizes explicit version pinning to make downstream impact visible when new versions are introduced.

🤖 Was this summary useful? React with 👍 or 👎

@augmentcode augmentcode Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Review completed. 2 suggestions posted.

Fix All in Augment

Comment augment review to trigger a new review at any time.

Comment thread README.markdown
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/`.

@augmentcode augmentcode Bot Aug 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

Comment thread README.markdown
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

@augmentcode augmentcode Bot Aug 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix This in Augment

🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.

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.

1 participant