Skip to content

Standardize maturity field across all collection YAML manifests #1319

@WilliamBerryiii

Description

@WilliamBerryiii

Standardize maturity field across all collection YAML manifests

Summary

An audit of all 14 collection YAML manifests against the Docusaurus site data (docs/docusaurus/src/data/collectionCards.ts) reveals inconsistent, missing, and conflicting maturity metadata. This blocks reliable downstream consumption by #1317 (dynamic Docusaurus generation) and #1318 (maturity badge visuals), and undermines the maturity filtering added in #1256.

/cc @katriendg

Current State

Collection Docusaurus YAML Manifest Status
ado Stable (missing) Gap — no maturity: field
coding-standards Stable plugin-level: experimental Conflict — Docusaurus says Stable, all plugins say experimental
data-science Stable plugin-level: experimental Conflict — Docusaurus says Stable, all plugins say experimental
design-thinking Preview preview Match
experimental Experimental experimental Match
github Stable (missing) Gap — no maturity: field
gitlab Experimental (missing) Gap — no maturity: field
hve-core Stable (missing) Gap — no maturity: field
hve-core-all (not in Docusaurus) (missing) Gap — meta-collection, needs decision
installer (not in Docusaurus) (missing) Gap — meta-collection, needs decision
jira Experimental (missing) Gap — no maturity: field
project-planning Stable plugin-level: experimental Conflict — Docusaurus says Stable, all plugins say experimental
rai-planning Experimental experimental Match
security Experimental plugin-level: experimental Partial — no collection-level field, but plugins carry it

Key Findings

  1. Only 3 of 14 manifests have a collection-level maturity: field (experimental, design-thinking, rai-planning)
  2. Zero manifests use the value stable — the most common Docusaurus assignment
  3. 3 direct conflicts where Docusaurus assigns Stable but plugin-level YAML says experimental (coding-standards, data-science, project-planning)
  4. Case mismatch: YAML uses lowercase (experimental, preview) while Docusaurus uses title-case (Experimental, Stable, Preview) — normalization needed at consumption boundaries
  5. Placement inconsistency: Existing maturity: fields appear at line 4 in some files and line 9 in others
  6. 2 meta-collections (hve-core-all, installer) have no Docusaurus presence and no maturity data — their maturity level needs a product decision

Impact

Proposed Remediation

1. Add maturity: to all 14 manifests

Place the field consistently after description: (line 4) using lowercase values (stable, preview, experimental). Reference values from Docusaurus as the source of truth for the 12 collections it covers.

Proposed assignments:

Collection Proposed Value Source
ado stable Docusaurus
coding-standards stable Docusaurus (overrides plugin-level experimental)
data-science stable Docusaurus (overrides plugin-level experimental)
design-thinking preview Already set
experimental experimental Already set
github stable Docusaurus
gitlab experimental Docusaurus
hve-core stable Docusaurus
hve-core-all stable Needs decision — meta-collection
installer stable Needs decision — meta-collection
jira experimental Docusaurus
project-planning stable Docusaurus (overrides plugin-level experimental)
rai-planning experimental Already set
security experimental Docusaurus

2. Add validation rule

Update Validate-Collections.ps1 to enforce that every collection YAML manifest includes a maturity: field with an allowed value (stable, preview, experimental).

3. Resolve the conflict question

Decide whether the 3 conflicting collections (coding-standards, data-science, project-planning) should be stable (matching Docusaurus) or experimental (matching their plugin-level items). This may require a product conversation about whether collection maturity represents the collection packaging or the content maturity.

4. Determine meta-collection maturity

Decide the maturity level for hve-core-all and installer, which are not represented in Docusaurus. Suggested default: stable since they are packaging meta-collections wrapping stable content.

Acceptance Criteria

  • All 14 collection YAML manifests contain a maturity: field
  • maturity: is placed consistently after description: across all manifests
  • Values use lowercase: stable, preview, or experimental
  • Validate-Collections.ps1 enforces maturity: presence and allowed values
  • Conflicts between Docusaurus and YAML are resolved with documented reasoning
  • Meta-collection maturity values are decided and documented
  • Plugin generation (npm run plugin:generate) succeeds after changes
  • All existing tests pass (npm run test:ps)
  • Lint passes (npm run lint:all)

Metadata

Metadata

Labels

Type

No type
No fields configured for issues without a type.

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions