Repository navigation
docs: consolidate bundle documentation and remove unusable examples - #5226
Merged
mnriem merged 2 commits intoNov 3, 2026
Merged
Conversation
Consolidate bundle guides under docs/bundles, update navigation and references, and remove obsolete illustrative bundles. Retarget bundle pin contract coverage to published first-party components. Assisted-by: GitHub Copilot App (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
Changes are still needed because the documentation has a grammar error and the contract test mishandles valid unpinned steps by passing "None" to version parsing.
2 open issues
What changed in this PR
Consolidates bundle documentation into a dedicated docs/bundles/ section, updates navigation and inbound links, and removes obsolete role-bundle examples. Contract tests now validate component pins from the shipped first-party bundles, while runtime bundle behavior remains unchanged.
Changes:
- Added canonical bundle overview, CLI, development, API, catalog, and publishing documentation.
- Updated documentation navigation, cross-references, community guidance, issue-template links, and bundle README links.
- Removed unusable example bundles and retargeted related contract and documentation tests.
| File | Description |
|---|---|
| tests/test_catalog_trust_docs.py | Updated as part of this pull request. |
| tests/contract/test_bundled_extension_versions.py | Updated as part of this pull request. |
| README.md | Updated as part of this pull request. |
| newsletters/2026-June.md | Updated as part of this pull request. |
| examples/bundles/security-researcher/README.md | Updated as part of this pull request. |
| examples/bundles/security-researcher/bundle.yml | Updated as part of this pull request. |
| examples/bundles/product-manager/README.md | Updated as part of this pull request. |
| examples/bundles/product-manager/bundle.yml | Updated as part of this pull request. |
| examples/bundles/developer/README.md | Updated as part of this pull request. |
| examples/bundles/developer/bundle.yml | Updated as part of this pull request. |
| examples/bundles/business-analyst/README.md | Updated as part of this pull request. |
| examples/bundles/business-analyst/bundle.yml | Updated as part of this pull request. |
| docs/toc.yml | Updated as part of this pull request. |
| docs/reference/workflows.md | Updated as part of this pull request. |
| docs/reference/overview.md | Updated as part of this pull request. |
| docs/reference/catalogs.md | Updated as part of this pull request. |
| docs/reference/bundles.md | Updated as part of this pull request. |
| docs/README.md | Updated as part of this pull request. |
| docs/install/air-gapped.md | Updated as part of this pull request. |
| docs/index.md | Updated as part of this pull request. |
| docs/guides/customization.md | Updated as part of this pull request. |
| docs/extensions/catalogs.md | Updated as part of this pull request. |
| docs/docfx.json | Updated as part of this pull request. |
| docs/community/overview.md | Updated as part of this pull request. |
| docs/community/bundles.md | Updated as part of this pull request. |
| docs/bundles/publishing.md | Updated as part of this pull request. |
| docs/bundles/overview.md | Updated as part of this pull request. |
| docs/bundles/developing.md | Updated as part of this pull request. |
| docs/bundles/cli.md | Updated as part of this pull request. |
| docs/bundles/catalogs.md | Updated as part of this pull request. |
| docs/bundles/api.md | Updated as part of this pull request. |
| bundles/bugfix/README.md | Updated as part of this pull request. |
| bundles/assess/README.md | Updated as part of this pull request. |
| .github/ISSUE_TEMPLATE/bundle_submission.yml | Updated as part of this pull request. |
Review effort: Lite (auto)
Skip valid unpinned steps when collecting component version pins, retain invalid-version coverage, and correct the developing guide introduction. Merge upstream/main and reconcile workflow and bundle documentation navigation, deletions, and cross-links. Assisted-by: GitHub Copilot App (model: GPT-6.1 Sol, autonomous) Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Consolidates bundle documentation under
docs/bundles/, following the structure used in #5225. Adds canonical overview, CLI, developing, API, catalogs, and publishing pages, with site navigation and inbound links updated together.Removes
docs/reference/bundles.mdwithout a forwarding stub. Keeps the community bundle listing and bundle-specific READMEs in place, moving shared authoring and publishing guidance to the canonical pages.Removes the unusable role-bundle examples under
examples/and their active documentation references. Retargets their version-contract checks to real first-party bundles and components without reducing the test collection count.This changes documentation, documentation build configuration, an issue-form documentation link, and related tests. Runtime behavior, first-party bundle manifests, catalogs, and submission automation are unchanged.
Testing
Tested locally with
uv run specify --helpRan existing tests with
uv sync && uv run pytestTested with a sample project (if applicable)
uv run specify --help— passed.LC_ALL=en_US.UTF-8 .venv/bin/python -m pytest tests/test_catalog_trust_docs.py tests/test_github_workflows.py tests/specify_cli/bundles tests/contract/test_bundled_extension_versions.py tests/contract/test_firstparty_bundle_catalog_consistency.py tests/contract/test_wheel_bundled_workflows.py -q— 1,460 passed.docfx docs/docfx.json(session-local DocFX installation) — passed with the same three pre-existing warnings as the baseline.git diff --check— passed.The full test suite and a sample-project agent process were not run for this documentation cleanup.
AI Disclosure
AI disclosure: Authored with GitHub Copilot App using GPT-6.1 Sol (
gpt-6.1-sol), in autonomous agent mode with runtime-default reasoning settings and human-directed scope. AI assistance covered documentation consolidation, obsolete example removal, navigation and reference updates, related test updates, validation, commit preparation, and PR preparation. No runtime behavior was changed.