microsoft / microsoft/hve-core

docs: update docs/customization/collections.md Maturity Filtering section for removed tier

Open Beginner friendly
#1,447 0 comments 0 reactions 0 assignees View on GitHub
documentation stale-docs
Dominant language
Python
Stars
1.5k
Forks
301
Avg merge
3d 3h
Merged PRs (30d)
92

Description

**Component:** Documentation

**Bug Description**

`docs/customization/collections.md` describes only four maturity tiers in the Maturity Filtering section, but the `collections/security.collection.yml` manifest now uses a fifth tier (`removed`) introduced by commit `19adc30` (feat(skills): add removed maturity tier and retire owasp-docker, #1444).

The schema at `scripts/linting/schemas/collection-manifest.schema.json` now enumerates `stable`, `preview`, `experimental`, `deprecated`, and `removed` at both the collection level and item level.

**What the documentation currently says:**

> Collections support **four** maturity tiers that control inclusion in generated plugin output:

| Tier | Meaning | Plugin Inclusion |
|----------------|--------------------------------------------|-----------------------------|
| `stable` | Production-ready, fully tested | Included in all channels |
| `preview` | Feature-complete but undergoing validation | Included in all channels |
| `experimental` | Early-stage, may change significantly | Excluded from stable builds |
| `deprecated` | Scheduled for removal | Excluded from new builds |

The hve-core-all Superset section also only mentions `maturity: experimental` and `maturity: deprecated` without acknowledging `removed` artifacts.

**Expected Behavior**

The Maturity Filtering section should say "five maturity tiers" and add a `removed` row:

| `removed` | Retired, excluded from every channel | Excluded from all channels and auto-discovery |

The hve-core-all Superset section should clarify that items marked `maturity: removed` are **excluded entirely** (not retained in the superset for visibility like experimental/deprecated items).

**Steps to Reproduce**

See commit `19adc30` which:
- Updated `scripts/linting/schemas/collection-manifest.schema.json` to add `removed` to the `maturity` enum
- Marked `.github/skills/security/owasp-docker` as `maturity: removed` in `collections/security.collection.yml`

`docs/architecture/ai-artifacts.md` already documents the `removed` tier correctly (lines 319 and 360).

**Additional Context**

- File to update: `docs/customization/collections.md` (Maturity Filtering section, ~line 92, and hve-core-all Superset section, ~line 175)
- Reference: `docs/architecture/ai-artifacts.md` already has the correct five-tier table for consistency
- Schema source: `scripts/linting/schemas/collection-manifest.schema.json`

> Generated by [Documentation Update Check](https://github.com/microsoft/hve-core/actions/runs/24917128493/agentic_workflow) · ● 1.9M · [◷](https://github.com/search?q=repo%3Amicrosoft%2Fhve-core+is%3Aissue+%22gh-aw-workflow-call-id%3A+microsoft%2Fhve-core%2Fdoc-update-check%22&type=issues)

Contributor guide

Open the contributing guide

Research direction

Start with docs/customization/collections.md, especially the Maturity Filtering section and hve-core-all Superset section. Compare them with the five-tier guidance in docs/architecture/ai-artifacts.md and the enum in scripts/linting/schemas/collection-manifest.schema.json. Done means both sections accurately explain the removed tier and its exclusion from all channels and auto-discovery.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
88/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.