feat: add category and effect as first-class fields in extension schema#2899
Open
mnriem wants to merge 5 commits into
Open
feat: add category and effect as first-class fields in extension schema#2899mnriem wants to merge 5 commits into
mnriem wants to merge 5 commits into
Conversation
Add `category` and `effect` as optional fields in the extension schema (`extension.yml`) and community catalog (`catalog.community.json`). Schema changes: - Valid categories: docs, code, process, integration, visibility - Valid effects: read-only, read-write - Both fields are optional (backward-compatible with existing extensions) - Validation raises ValidationError for invalid values when present Propagation: - Added `category` and `effect` to all 108 entries in catalog.community.json (populated from the existing docs/community/extensions.md table) - Updated extension template with commented category/effect fields - Updated add-community-extension skill with new JSON template fields - Updated `specify extension info` CLI output to display category/effect - Added properties to ExtensionManifest class Tests: - test_valid_category: all 5 category values pass - test_valid_effect: both effect values pass - test_invalid_category: invalid value raises ValidationError - test_invalid_effect: invalid value raises ValidationError - test_category_and_effect_optional: omitting fields still works Closes #2874 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Category is a free-form string (only validated as non-empty when present), while effect remains restricted to 'read-only' or 'read-write'. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Adds category and effect as optional, first-class fields in the extension manifest schema and surfaces them through the community catalog and CLI so tooling can rely on structured metadata rather than the manually maintained docs table.
Changes:
- Introduces
VALID_CATEGORIES/VALID_EFFECTS, validatesextension.categoryandextension.effectwhen present, and exposes them viaExtensionManifestproperties. - Extends
specify extension infooutput (catalog + local) to display category/effect when available. - Populates
extensions/catalog.community.jsonwith category/effect for community extensions and updates docs/template/skill guidance plus adds new tests.
Show a summary per file
| File | Description |
|---|---|
src/specify_cli/extensions.py |
Adds allowed-value constants, validates optional manifest fields, and exposes category/effect properties. |
src/specify_cli/__init__.py |
Prints category/effect in specify extension info for local and catalog extensions. |
extensions/catalog.community.json |
Adds category and effect across community catalog entries. |
extensions/template/extension.yml |
Updates the author template to include category/effect guidance. |
docs/community/extensions.md |
Adds a tip explaining the new manifest/catalog fields. |
.github/skills/add-community-extension/SKILL.md |
Updates the community-extension skill template to include category/effect in catalog entries. |
tests/test_extensions.py |
Adds tests for valid/invalid category/effect values and optional/back-compat behavior. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 7/7 changed files
- Comments generated: 4
- Add type guard before 'in' check for effect to prevent TypeError on unhashable YAML values (list/dict) - Comment out category/effect in template so authors must opt in - Use VALID_EFFECTS constant in test instead of hard-coded values Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Comment on lines
+23
to
+24
| > [!TIP] | ||
| > Extension authors can declare `category` and `effect` in their `extension.yml` under the `extension:` block. These fields are also available in `catalog.community.json` for tooling and the CLI (`specify extension info`). |
Comment on lines
+92
to
+93
| **Category** — free-form string; common values: `docs`, `code`, `process`, `integration`, `visibility` | ||
| **Effect** — one of: `read-only`, `read-write` |
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.
Summary
Adds
categoryandeffectas optional fields in the extension schema (extension.yml) and propagates them tocatalog.community.json, replacing the manual-only markdown table approach.Changes
Schema (
src/specify_cli/extensions.py)VALID_EFFECTSconstant for the closed set of allowed effect valuesVALID_EFFECTSExtensionManifest._validate()— raisesValidationErrorfor invalid values when presentcategoryandeffectproperties toExtensionManifestCatalog (
extensions/catalog.community.json)categoryandeffectfields to all 108 extension entries (populated from the existing docs table)CLI (
src/specify_cli/__init__.py)specify extension infonow displays category and effect for both catalog and local extensionsTemplate & Docs
extensions/template/extension.ymlwith commented category/effect fieldsadd-community-extensionskill with new catalog JSON templatedocs/community/extensions.mdnoting schema availabilityTests
Extension authors can now declare:
Backward Compatibility
Both fields are optional — existing extensions without them continue to work unchanged.
Closes #2874