Skip to content

feat(extension): Collection-Level Maturity Gating for Release Channel Control #467

@katriendg

Description

@katriendg

Issue Description

Add a maturity field to the extension collection manifest schema so that entire collections can be marked as experimental or deprecated, controlling whether they are released in PreRelease and/or Stable channels.

Motivation

Individual artifacts already carry maturity levels (stable, preview, experimental, deprecated) in the AI Artifacts Registry. However, no equivalent concept exists at the collection level. When a new persona collection is being developed or tested, it should be possible to mark the entire collection as experimental so it is only packaged and published as a PreRelease extension, never as a Stable release. Likewise, when a collection is retired, marking it deprecated should prevent it from being released in either channel.

This enables a safe lifecycle for persona collections:

  1. experimental: Collection is under active development. Built and published as PreRelease only. Users who install the PreRelease channel receive it; Stable channel users never see it.
  2. preview: Collection is feature-complete but not yet validated at scale. Built for both PreRelease and Stable channels (same as artifact-level preview behavior).
  3. stable: Collection is production-ready. Built and published in both channels (default, current behavior).
  4. deprecated: Collection is retired. No longer built or published in any channel. Existing installations remain but receive no updates.

Deliverables

1. Collection Manifest Schema Update

Update scripts/linting/schemas/collection.schema.json to add an optional maturity property:

"maturity": {
    "type": "string",
    "enum": ["stable", "preview", "experimental", "deprecated"],
    "default": "stable",
    "description": "Collection-level maturity controlling release channel eligibility. Experimental collections are released only as PreRelease. Deprecated collections are excluded from all releases."
}

The field is optional with a default of stable to maintain backward compatibility with existing collection manifests that omit it.

2. Collection Manifest Updates

Add maturity field to existing and future collection manifests in extension/collections/:

Collection Maturity Rationale
hve-core-all stable Primary full-release package, always published
developer stable First persona collection, validated in current PR
Future personas experimental New collections start as experimental until proven

3. Packaging Script Integration

Update scripts/extension/Package-Extension.ps1 and scripts/extension/Prepare-Extension.ps1 to:

  • Read the maturity field from the collection manifest
  • When building for a Stable release channel, skip collections with experimental maturity
  • When building for any channel, skip collections with deprecated maturity
  • Log a clear message when a collection is skipped due to maturity gating

Channel-to-maturity eligibility matrix:

Collection Maturity PreRelease Channel Stable Channel
stable Yes Yes
preview Yes Yes
experimental Yes No
deprecated No No

4. CI/CD Workflow Integration

Update the extension packaging workflow (.github/workflows/extension-package.yml) to:

  • Pass the release channel context to packaging scripts
  • Respect collection maturity when determining which collections to build in the matrix strategy
  • Ensure deprecated collections are excluded from the build matrix entirely

5. Validation Integration

Update scripts/linting/Validate-ArtifactRegistry.ps1 or add collection-level validation to:

  • Validate that collection manifest maturity values are valid enum members
  • Warn when a deprecated collection still exists in the build matrix
  • Warn when an experimental collection has been experimental for longer than a configurable threshold (optional, future)

Acceptance Criteria

  • Collection manifest schema supports an optional maturity field with enum values stable, preview, experimental, deprecated
  • Existing collection manifests without maturity default to stable (backward compatible)
  • Packaging scripts skip experimental collections when building for Stable channel
  • Packaging scripts skip deprecated collections for all channels
  • CI/CD build matrix respects collection maturity gating
  • Validation catches invalid maturity values in collection manifests
  • A collection can transition from experimental to stable by changing a single field

Technical Notes

  • The collection-level maturity is independent of artifact-level maturity. A stable collection can contain preview artifacts (which are filtered by the existing artifact-level channel logic). The collection maturity gates the entire package, while artifact maturity gates individual files within it.
  • The deprecated state is terminal: once set, the collection should not be republished. Consider adding a workflow guard that fails the build if a deprecated collection is accidentally included.
  • This aligns with the existing maturity enum values used in the AI Artifacts Registry schema (stable, preview, experimental, deprecated), maintaining vocabulary consistency across the system.

Additional Context

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Type

No type

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions