Feature Card Governance: A Repo‑First Versioning & Release Workflow for Machine‑Readable Feature Libraries

Start by representing each feature card as a small JSON‑LD document stored in a single repo (or mono-repo directory) — one file per card. JSON‑LD gives you a predictable shape and a vocabulary you can extend later without breaking consumers. Use a compact context to keep files readable while ensuring each card has stable, resolvable properties (id, title, description, status, schema, owner, compatibility). JSON‑LD best practices and the JSON‑LD spec explain why a linked-data container simplifies evolution and machine discovery. (json-ld.org)

Design core attributes with consumers in mind. Include a semantic identifier (see next section), a human title and short description, a machine-readable schema or pointer (JSON Schema or OpenAPI fragment) that defines inputs/outputs, an ops status (draft|stable|deprecated|retired), owner/team, and a changelog pointer. Keep the surface small — consumers should be able to validate, index, and decide whether to surface a card to an agent in under a single HTTP request or file parse.

Assign each card a semantic ID that reflects product domain and intent (for example: /feature/auth/passwordless or com.appwispr.feature.auth.passwordless). Semantic IDs make cards discoverable and readable to both humans and machines. Treat the ID as the canonical lookup key for agents and partner integrations.

For releases, adopt a semver-like version string inside the card (major.minor.patch[-prerelease][+meta]). SemVer is widely understood and clarifies compatibility expectations: major bumps signal contract-breaking changes, minors add non-breaking capabilities, and patches fix metadata or typos. Record the version in the card’s top-level metadata and in the changelog entry to keep traceability between commits, tags, and published artifacts. Standards and guidance about versioning and semantic versioning are broadly available. (en.wikipedia.org)

Instead of burying release notes in prose-only files, maintain a changelog JSON‑LD per feature card (or a single changelog index) that records each version entry with date, author, summary, and minimal migration guidance. Machine-readable changelogs let search, agents, and automation decide whether to surface a card or trigger migration workflows without parsing freeform markdown. Patterns for changelogs exist (e.g., Common Changelog), but JSON‑LD gives machine clients typed fields and links to other artifacts. (common-changelog.org)

Keep changelog entries short and focused: version, ISO 8601 date, kind (breaking|non-breaking|patch), short summary, migration steps (if any), and reference commit/tag. Use the changelog to drive release metadata in CI and as the authoritative record for rollbacks.

Gate all changes with CI steps that validate (a) JSON‑LD syntax, (b) a JSON Schema contract for the card shape, and (c) the declared feature schema (input/output) against JSON Schema or OpenAPI. Use existing tooling: JSON Schema validators and GitHub Actions for schema validation are mature and simple to integrate. Failing fast in CI prevents malformed cards from reaching downstream agents. (github.com)

Add higher-level checks: ensure version increases correctly, prevent changing @id without an explicit migration workflow, and verify changelog entries accompanied the version bump. Optionally run lightweight static checks that ensure referenced owners exist and that status transitions follow policy (draft → stable → deprecated → retired). These are easy to encode as GitHub Action steps or simple Node/Python scripts run in the pipeline.

Publish releases using git tags and a small release script that collects changed cards, verifies CI green, and publishes an index or registry artifact (e.g., features/index.jsonld) to a stable location (GitHub Pages, S3, or package registry). The published index is what agents and partners point to for discovery; keep it immutable and versioned so consumers can pin to a specific registry snapshot.

Build rollback into the workflow: reversible releases are simply new releases that mark the previous version as preferred and include a changelog entry explaining the reason and mitigation. Because cards and changelogs are machine-readable and immutably stored, agents can automatically prefer pinned versions or respect the registry’s preferred flag. Operational guidance from feature-flag and release-practices writing recommends incremental change and easy rollback as first-class functions. (split.io)