docs(#3858): add AIResource examples and registration docs#3859
Conversation
Add example catalog-info.yaml files for git-backed and OCI-backed AIResource entities to the examples/ directory. Extend the catalog-backend-module-ai-resource-extensions README with schema field reference, registration guidance for both git and OCI sources, accepted spec.scope values, and documentation of the OCI validation-only behavior and its air-gap rationale. Closes #3858 Assisted-by: Claude
Changed Packages
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #3859 +/- ##
==========================================
- Coverage 56.63% 56.62% -0.01%
==========================================
Files 2372 2372
Lines 95057 95051 -6
Branches 26562 26559 -3
==========================================
- Hits 53832 53823 -9
- Misses 39653 39656 +3
Partials 1572 1572
*This pull request uses carry forward flags. Click here to find out more. Continue to review full report in Codecov by Harness.
🚀 New features to boost your workflow:
|
johnmcollier
left a comment
johnmcollier
left a comment
There was a problem hiding this comment.
Review
Solid docs PR that covers the #3858 tasks (examples + schema/registration/OCI air-gap docs). CI looks good, and the scope / OCI format guidance matches the shipped processors. A few accuracy issues conflict with the issue’s “keep docs accurate to what is implemented on main” guidance.
Major: Schema “Required” overstates shipped validation
In the new Schema Fields table, spec.type, spec.lifecycle, spec.owner, and spec.location.* are marked required. This module currently only enforces:
- optional
spec.scope∈{organization, product, team}(AIResourceExtensionsProcessor) oci://format whenspec.location.typeisoci(AIResourceOciProcessor)
The processors pass through entities with no location and do not require owner/type/lifecycle.
Suggestion: Mark only what this module validates, or split “typical / upstream” vs “enforced here.” At minimum, footnote that requiredness is not enforced by these processors.
Major: Git + UrlReaderProcessor / source-location claim is inaccurate for current code
The git registration steps say UrlReaderProcessor uses backstage.io/source-location for ingestion. In Backstage, that processor reads the registered catalog location URL (the YAML file). backstage.io/source-location is source metadata, not what drives entity ingestion. There is also no shipped processor that warns on a missing annotation.
Including the annotation in the example as recommended convention is fine — please just drop the causal link to UrlReaderProcessor unless/until that path is verified.
Suggestion: Rephrase to: register the entity YAML via a normal catalog URL/location; for git-backed assets, set backstage.io/source-location (and spec.location) so consumers can find the repo.
Minor: OCI example spec.type mismatches the asset
examples/ai-resource-oci.yaml describes a summarization skill pack but uses type: model. Consider type: skills (or similar) so the example matches its description.
Minor: Missing changeset
The changeset bot flagged the package whose README changed. A docs patch changeset would be consistent with repo practice for published packages.
Nit
Existing Validation blurb + new OCI Validation-Only Behavior section overlap a bit — fine to keep the expanded air-gap explanation.
What looks good
- Examples under
examples/with correct relative README links - OCI docs match processor checks and clearly state zero registry I/O
spec.scopevalues matchVALID_AI_RESOURCE_SCOPES- Registration guidance (URL UI / catalog location) matches the issue
- Out of scope respected (docs/examples only)
Happy to approve once the two major accuracy items are addressed.
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 10:08 PM UTC · Completed 10:26 PM UTC |
|
/fs-fix fix and address review comments |
|
🤖 Finished Fix · ✅ Success · Started 10:11 PM UTC · Completed 10:26 PM UTC |
- Replace misleading "Required" column with "Enforced by this module" and add footnote clarifying these processors do not validate spec.type, spec.lifecycle, spec.owner, or spec.location presence - Remove inaccurate UrlReaderProcessor / source-location ingestion claim from README and git example; rephrase to describe annotation as consumer-facing metadata - Change OCI example spec.type from "model" to "skills" to match the asset description (summarization skill pack) - Add docs patch changeset for the README changes Addresses review feedback on #3859 Assisted-by: Claude
🔧 Fix agent — iteration 1 (human-triggered)Addressed all 4 review findings: corrected schema table to reflect actual processor enforcement, removed inaccurate UrlReaderProcessor claim, fixed OCI example type mismatch, and added docs patch changeset. Fixed (4):
Tests: passed Updated by fullsend fix agent |
ReviewReason: stale-head The review agent reviewed commit |
|
/fs-review |
|
johnmcollier
left a comment
johnmcollier
left a comment
There was a problem hiding this comment.
Re-review
All prior feedback is addressed on 7348f87:
- Schema enforcement — “Required” replaced with “Enforced by this module”; footnote correctly scopes non-enforced fields;
spec.scope/ OCI target rules match the processors. - Git registration — UrlReaderProcessor / source-location ingestion claim removed; annotation framed as consumer-facing metadata.
- OCI example —
spec.type: skillsmatches the skill-pack description. - Changeset — docs patch changeset added.
Docs and examples stay accurate to shipped validation (scope enum + OCI format-only, zero registry I/O). CI green. Approving.
|
🤖 Finished Retro · ✅ Success · Started 10:21 PM UTC · Completed 10:33 PM UTC |
Retro: PR #3859 — docs(#3858): add AIResource examples and registration docsTimeline
Workflow QualityOverall: Reasonable workflow — 1 rework cycle, fix agent addressed all findings in a single iteration. Main waste was the review-fix race ($5.38 in review tokens discarded). Code agent: Produced docs with 2 major accuracy issues: (1) schema table marked fields as "Required" that the processors don't enforce, (2) made an inaccurate claim about Fix agent: Excellent — addressed all 4 human review findings correctly in one iteration. Review agent vs human review:
Evidence for Existing Issues
Proposals filed
|
1 participant
Add example catalog-info.yaml files for git-backed and OCI-backed AIResource entities to the examples/ directory. Extend the catalog-backend-module-ai-resource-extensions README with schema field reference, registration guidance for both git and OCI sources, accepted spec.scope values, and documentation of the OCI validation-only behavior and its air-gap rationale.
Assisted-by: Claude
Closes #3858
Post-script verification
agent/3858-airesource-examples-docs)f48c72a4fe5aea6f29f623a2f2d649cec96da23e..HEAD)