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
- Only 3 of 14 manifests have a collection-level
maturity: field (experimental, design-thinking, rai-planning)
- Zero manifests use the value
stable — the most common Docusaurus assignment
- 3 direct conflicts where Docusaurus assigns
Stable but plugin-level YAML says experimental (coding-standards, data-science, project-planning)
- Case mismatch: YAML uses lowercase (
experimental, preview) while Docusaurus uses title-case (Experimental, Stable, Preview) — normalization needed at consumption boundaries
- Placement inconsistency: Existing
maturity: fields appear at line 4 in some files and line 9 in others
- 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
Standardize
maturityfield across all collection YAML manifestsSummary
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
adomaturity:fieldcoding-standardsexperimentaldata-scienceexperimentaldesign-thinkingpreviewexperimentalexperimentalgithubmaturity:fieldgitlabmaturity:fieldhve-corematurity:fieldhve-core-allinstallerjiramaturity:fieldproject-planningexperimentalrai-planningexperimentalsecurityexperimentalKey Findings
maturity:field (experimental,design-thinking,rai-planning)stable— the most common Docusaurus assignmentStablebut plugin-level YAML saysexperimental(coding-standards,data-science,project-planning)experimental,preview) while Docusaurus uses title-case (Experimental,Stable,Preview) — normalization needed at consumption boundariesmaturity:fields appear at line 4 in some files and line 9 in othershve-core-all,installer) have no Docusaurus presence and no maturity data — their maturity level needs a product decisionImpact
Prepare-Extension.ps1maturity filtering (from collection.md: auto-generation, maturity safety, and custom header support #1256) operates on collection-levelmaturity:— only 3 of 14 collections are currently filterableValidate-Collections.ps1does not enforce presence ofmaturity:— missing values pass validation silentlyProposed Remediation
1. Add
maturity:to all 14 manifestsPlace 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:
adostablecoding-standardsstableexperimental)data-sciencestableexperimental)design-thinkingpreviewexperimentalexperimentalgithubstablegitlabexperimentalhve-corestablehve-core-allstableinstallerstablejiraexperimentalproject-planningstableexperimental)rai-planningexperimentalsecurityexperimental2. Add validation rule
Update
Validate-Collections.ps1to enforce that every collection YAML manifest includes amaturity: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 bestable(matching Docusaurus) orexperimental(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-allandinstaller, which are not represented in Docusaurus. Suggested default:stablesince they are packaging meta-collections wrapping stable content.Acceptance Criteria
maturity:fieldmaturity:is placed consistently afterdescription:across all manifestsstable,preview, orexperimentalValidate-Collections.ps1enforcesmaturity:presence and allowed valuesnpm run plugin:generate) succeeds after changesnpm run test:ps)npm run lint:all)