Skip to content

feat(collections): standardize maturity field across all 14 collection YAML manifests#1432

Draft
MauroDruwel wants to merge 1 commit intomicrosoft:mainfrom
MauroDruwel:feat/1319-collection-maturity-standardization
Draft

feat(collections): standardize maturity field across all 14 collection YAML manifests#1432
MauroDruwel wants to merge 1 commit intomicrosoft:mainfrom
MauroDruwel:feat/1319-collection-maturity-standardization

Conversation

@MauroDruwel
Copy link
Copy Markdown
Contributor

Summary

Closes #1319

Audited all 14 collection YAML manifests against docs/docusaurus/src/data/collectionCards.ts and resolved every gap, conflict, and placement inconsistency identified in the issue.

Changes

1. Collection YAML manifests — maturity field added/corrected

maturity: is now placed consistently after description: across all 14 manifests.

Collection Before After Source
ado (missing) stable Docusaurus
coding-standards (missing, plugin-level: experimental) stable Docusaurus
data-science (missing, plugin-level: experimental) stable Docusaurus
design-thinking preview (wrong position — after tags) preview (after description) Already set
experimental experimental unchanged Already set
github (missing) stable Docusaurus
gitlab (missing) experimental Docusaurus
hve-core (missing) stable Docusaurus
hve-core-all (missing) stable Meta-collection wrapping stable content
installer (missing) stable Meta-collection wrapping stable content
jira (missing) experimental Docusaurus
project-planning (missing, plugin-level: experimental) stable Docusaurus
rai-planning experimental unchanged Already set
security (missing, plugin-level: experimental) experimental Docusaurus

2. Validate-Collections.ps1 — maturity is now required

Changed maturity: from an optional field (silently passes if absent) to a required field. Before: the validator only checked values when the field was present. After: missing maturity: field triggers a validation error with message missing required field 'maturity'.

The new check follows the same pattern as other field validations (id, name, description) and uses the existing $allowedMaturities set: stable, preview, experimental, deprecated.

3. Validate-Collections.Tests.ps1 — tests updated for new behavior

  • Changed "Passes validation for collection with omitted maturity""Fails validation for collection with omitted maturity" to match enforced behavior.
  • Added maturity = 'stable' to all other test manifests that were constructed without a maturity field (these tests were verifying unrelated behavior — path validation, folder naming, marker parsing — and needed the field to satisfy the new requirement).

Conflict Resolution: Collection Maturity vs. Plugin-Item Maturity

Three collections (coding-standards, data-science, project-planning) show experimental at the plugin-item level but Stable in Docusaurus. This PR sets collection-level maturity to stable matching Docusaurus, for the following reason:

Collection maturity represents the collection's distribution readiness (is it packaged, tested, and safe to install?), not the stability of every individual artifact it contains. These three collections are production-distributed, well-maintained packages. Individual items that are experimental carry their own item-level maturity: field which downstream consumers (Prepare-Extension.ps1 maturity filtering, #1317 badge rendering) already read separately.

Meta-Collection Decision

hve-core-all and installer are not present in Docusaurus. Both are packaging meta-collections wrapping stable production content, so stable is the correct value.

Testing

Command Result
npm run lint:collections-metadata ✅ 14 collections validated, 0 errors
npm run test:ps -- -TestPath scripts/tests/collections/ ✅ 105 tests passed, 0 failed
npm run plugin:generate ✅ 14 plugin(s) generated

Manual testing was not performed.

…n manifests (microsoft#1319)

- Add collection-level maturity: field to 11 collection YAMLs that were missing it
- Move maturity: field in design-thinking.collection.yml to consistent position after description:
- Placement is after description: and before notice:/tags:/items: across all manifests

Proposed maturity assignments (Docusaurus as source of truth):
- ado, coding-standards, data-science, github, hve-core, hve-core-all, installer,
  project-planning: stable
- design-thinking: preview (already set, position corrected)
- experimental, gitlab, jira, rai-planning, security: experimental

Note on coding-standards, data-science, project-planning: Docusaurus assigns these as
Stable at the collection level even though individual plugin items carry experimental
maturity. Collection maturity represents the collection's distribution readiness, not
the stability of every individual artifact it contains.

Note on hve-core-all, installer: not in Docusaurus; both wrap stable packaging
so stable is the appropriate default.

- Update Validate-Collections.ps1 to enforce maturity: presence as a required field
  (previously optional — missing values passed silently)
- Update Validate-Collections.Tests.ps1: change "Passes validation for collection
  with omitted maturity" to "Fails validation for collection with omitted maturity"
  and add maturity: stable to all other test manifests that were created without it

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
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.

Standardize maturity field across all collection YAML manifests

1 participant