-
Notifications
You must be signed in to change notification settings - Fork 125
Description
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:
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.preview: Collection is feature-complete but not yet validated at scale. Built for both PreRelease and Stable channels (same as artifact-level preview behavior).stable: Collection is production-ready. Built and published in both channels (default, current behavior).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
maturityfield from the collection manifest - When building for a Stable release channel, skip collections with
experimentalmaturity - When building for any channel, skip collections with
deprecatedmaturity - 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
maturityvalues are valid enum members - Warn when a
deprecatedcollection still exists in the build matrix - Warn when an
experimentalcollection has been experimental for longer than a configurable threshold (optional, future)
Acceptance Criteria
- Collection manifest schema supports an optional
maturityfield with enum valuesstable,preview,experimental,deprecated - Existing collection manifests without
maturitydefault tostable(backward compatible) - Packaging scripts skip
experimentalcollections when building for Stable channel - Packaging scripts skip
deprecatedcollections for all channels - CI/CD build matrix respects collection maturity gating
- Validation catches invalid maturity values in collection manifests
- A collection can transition from
experimentaltostableby changing a single field
Technical Notes
- The collection-level maturity is independent of artifact-level maturity. A
stablecollection can containpreviewartifacts (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
deprecatedstate 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
maturityenum values used in the AI Artifacts Registry schema (stable,preview,experimental,deprecated), maintaining vocabulary consistency across the system.
Additional Context
- Collection schema:
scripts/linting/schemas/collection.schema.json - Existing collection manifests:
extension/collections/ - Registry maturity enum:
scripts/linting/schemas/ai-artifacts-registry.schema.json(artifact-level precedent) - Packaging scripts:
scripts/extension/Prepare-Extension.ps1,scripts/extension/Package-Extension.ps1 - CI workflow:
.github/workflows/extension-package.yml - Depends on: Phase 2 (feat: Multi-Package Extension Build System #433, Multi-Package Build System) for collection-aware packaging
- Depends on: Phase 5 (feat: Publishing Infrastructure and CI/CD for Multi-Package Distribution #436, Publishing Infrastructure) for CI/CD multi-package workflow
- Parent epic: feat: Persona-Based Extension Distribution #431 (Persona-Based Extension Distribution)