docs(#4042): add migration design document for upstream entity kinds - #4221
docs(#4042): add migration design document for upstream entity kinds#4221fullsend-ai-coder[bot] wants to merge 8 commits into
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4221 +/- ##
==========================================
+ Coverage 58.33% 58.38% +0.05%
==========================================
Files 2432 2435 +3
Lines 96774 96916 +142
Branches 26888 26930 +42
==========================================
+ Hits 56451 56588 +137
- Misses 40130 40135 +5
Partials 193 193
*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:
|
|
/fs-fix CI issues (prettier) |
|
🤖 Finished Fix · ✅ Success · Started 9:41 AM UTC · Completed 9:52 AM UTC Commit: |
🔧 Fix agent — iteration 1 (human-triggered)Applied prettier formatting to the migration design document. The file had markdown table column alignment inconsistencies and italic marker style issues (text vs text) that caused the CI prettier:check gate to fail. All changes are cosmetic — no content was modified. Fixed (1):
Tests: passed Updated by fullsend fix agent |
Run prettier on the design.md file to fix markdown table alignment and italic marker formatting that was causing CI failures. Addresses review feedback on #4221
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 9:58 AM UTC · Completed 10:15 AM UTC Commit: |
ReviewFindingsMedium
Low
Previous runReviewFindingsHigh
Low
Next steps:
Previous run (2)ReviewFindingsMedium
Low
Labels: PR adds documentation under workspaces/boost/openspec/ Next steps:
|
![fullsend-ai-review[bot]](https://avatars.githubusercontent.com/in/3478501?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
fullsend-ai-review
Bot
added
documentation
|
/fs-fix Address open review findings on this docs PR. Keep content accurate; do not invent new migration mechanisms. Must fix (correctness / process):
Must fix (convention):
Should fix (light polish):
Already done — skip: prettier formatting (commit Out of scope for this fix: obtaining real architect sign-off; implementing CLI/annotation publish (#4220); executing migration. |
|
🤖 Finished Fix · ✅ Success · Started 10:33 AM UTC · Completed 10:42 AM UTC Commit: |
🔧 Fix agent — iteration 2 (human-triggered)Addressed all 5 review findings (1, 2, 4, 5, 6). Renamed design.md to migration-plan.md. Fixed dual-filter backward-compat to use annotation-only queries with full Backstage path. Corrected entity-ref auto-rewrite claim to note inbound refs are not auto-rewritten. Added Context and Risks sections. Fixed (5):
Tests: passed Updated by fullsend fix agent |
- Rename design.md to migration-plan.md with H1 "Migration Plan: ..." to follow specs/ directory conventions (finding 4) - Fix dual-filter backward-compat: change "old" pattern to annotation-only using full Backstage path metadata.annotations.rhdh.io/ai-asset-category; explicitly document that annotation retention does NOT preserve kind-based filters after a kind change (Resource->API); note casing-only changes (AIResource->AiResource) are unaffected due to case-insensitive kind matching (finding 1) - Soften entity-ref auto-rewrite claim: clarify that migrated entity's own ref changes but inbound relationships and hardcoded refs are NOT auto-rewritten; add inbound ref migration plan to Future Work (finding 2) - Add Context and Risks sections for document navigability (finding 6) Addresses review feedback on #4221
|
/fs-fix CI issues (prettier) |
|
🤖 Finished Fix · ✅ Success · Started 11:02 AM UTC · Completed 11:13 AM UTC Commit: |
Apply prettier table column width normalization to Entity References and API Queries tables in migration-plan.md. Fixes CI prettier check. Addresses review feedback on #4221
🔧 Fix agent — iteration 3 (human-triggered)Fixed CI prettier check by running prettier --write on migration-plan.md from the boost workspace (which uses @backstage/cli/config/prettier). Changes are purely whitespace normalization in markdown table column widths. Fixed (1):
Tests: passed Updated by fullsend fix agent |
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 11:19 AM UTC · Completed 11:35 AM UTC Commit: |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Create the RHIDP-15302 migration design document mapping current RHDH AI-asset entities to upstream Backstage entity kind targets. The document covers all seven categories from Decision 1 (agent, skill, rule, skill-bundle, mcp-server, ai-model, model-server) with: - Current-to-upstream mapping table with confidence levels - Field-level transformation rules per category - Consumer-facing changes (UI filters, entity refs, API queries) - Backward compatibility strategy (annotation retention for one major version) - Sign-off section (pending RHDH architect review) - Upstream tracking table and out-of-scope boundaries Mapping tables are consistent with the reconciliation in #4189. Annotation spec publish and migration CLI are split to #4220.
Run prettier on the design.md file to fix markdown table alignment and italic marker formatting that was causing CI failures. Addresses review feedback on #4221
- Rename design.md to migration-plan.md with H1 "Migration Plan: ..." to follow specs/ directory conventions (finding 4) - Fix dual-filter backward-compat: change "old" pattern to annotation-only using full Backstage path metadata.annotations.rhdh.io/ai-asset-category; explicitly document that annotation retention does NOT preserve kind-based filters after a kind change (Resource->API); note casing-only changes (AIResource->AiResource) are unaffected due to case-insensitive kind matching (finding 1) - Soften entity-ref auto-rewrite claim: clarify that migrated entity's own ref changes but inbound relationships and hardcoded refs are NOT auto-rewritten; add inbound ref migration plan to Future Work (finding 2) - Add Context and Risks sections for document navigability (finding 6) Addresses review feedback on #4221
Apply prettier table column width normalization to Entity References and API Queries tables in migration-plan.md. Fixes CI prettier check. Addresses review feedback on #4221
Align skill/rule filter impact with case-insensitive kind matching, scope N+1 annotation removal to migrated categories, use full annotation filter paths, and document concrete AiResource field transforms plus the #4164 agent baseline caveat. Sync migration-readiness/spec.md and mark tasks 8.1–8.4 done. Part of #4042
06e8a67 to
b56ca4b
Compare
|
@gabemontero — please LGTM this as the canonical RHIDP-15302 design SoT (
|
Fix entity-identity cutover wording, refresh #4164/#34261/#33575 status, harden MCP remotes, and sync boost runtime facts in spec.md.
|
Updated as #4164 landed |
|
/fs-review |
|
🤖 Finished Review · ✅ Success · Started 1:31 PM UTC · Completed 1:49 PM UTC Commit: |
Superseded by updated review
fullsend-ai-review
Bot
added
the
requires-manual-review
|
FYI @mareklibra I'll most likely be landing #4211 later today my time We are past the point of having any confidence of note that my upstream API extension for ai model servers will land in a version of backstage that can be consume by 2.1 Hence, #4211 will provide an |
Note boost isAiAsset gaps for skill-bundle/model-server, align dash punctuation and stub Date, and clarify RHDH architect sign-off wording.
|
gabemontero
left a comment
gabemontero
left a comment
There was a problem hiding this comment.
Various clarification @mareklibra
Also, I've crafted #4260 (the first of a couple of potential proposals) for updating existing code in the boost frontend and the 2 entity providers
I consider your work here as the driver for properly adjusting future work (i.e. the 29 github issues, pending RHDHPLAN-1507/1508/1510/1513 content)
will follow up in slack as well per my message to you earlier today
| ## Context | ||
|
|
||
| This plan exists because RHDH ships custom entity kinds and annotations | ||
| (`AIResource`, `rhdh.io/ai-asset-category`, etc.) that diverge from |
There was a problem hiding this comment.
some comments in the ai-integrations code may say AIResource with the I capitalized, and there are some downstream supporting types in ai-integrations with the I capitalized (AIResourceScope for example), but there is no entity kind called AIResource getting introduced.
Only the upstream AiResource with a lower case i
And our extension for agents noted below is the lower case i naming convention
There was a problem hiding this comment.
@johnmcollier is trying to address all this with #4246 @mareklibra
thanks
| - **Upstream PR rejection:** The model-server mapping | ||
| (`Resource` -> `API`) depends on an open PR | ||
| ([#34476](https://github.com/backstage/backstage/pull/34476)). If | ||
| declined, that row must be redesigned. |
There was a problem hiding this comment.
So #4211 is what we are going with for now regardless if my upstream PR merges, because at this point it may be too late for it to get into a backstage version that can be pulled into 2.1
If my proposal merges, schema wise the types are identical, to it is a byte to byte migration when the time comes
If they never devise a standard way of expressing ai model servers as entities, we will stick with AiModelServerAPI from #4211
If and only if they devise a radically different mapping will we then deal with a migration.
| (`resource:` -> `api:`), not an in-place rewrite of the same entity. | ||
| Inbound relationships and hardcoded refs in other entities are **not** | ||
| automatically rewritten by the catalog — a separate migration plan | ||
| for ref consumers is required (see [Future Work](#future-work)). |
There was a problem hiding this comment.
Not worried about intra release migration, nor of the component/resource/api tuples ai-integration originally provide (they were only at dev preview and can be broken/re-worked).
UI /console filters should be adjusted to only deal with the new AiModelServerAPI entity kind
| #32062. Downstream | ||
| [rhdh-plugins#4164](https://github.com/redhat-developer/rhdh-plugins/pull/4164) | ||
| (merged) ships `AiResource` / `spec.type: agent` in ai-integrations, | ||
| while Decision 1 / boost still classify agents as |
There was a problem hiding this comment.
we'll have to change code, but again, not worried about migrating data in postgresql during 2.1 development, if that is what you are referring to here
| | `model-server` | Resource | `ai-model-server` | `rhdh.io/ai-asset-category: model-server` | Candidate `API` / `ai-model-server` ([#34476](https://github.com/backstage/backstage/pull/34476), open) | Medium/Low | | ||
| | `ai-model` | Resource | `ai-model` | `rhdh.io/ai-asset-category: ai-model` | No solid upstream kind yet | Low | | ||
| | `skill-bundle` | AIResource | `ai-skill-bundle` | `rhdh.io/ai-asset-category: skill-bundle` | No upstream kind | Low | | ||
| | `agent` | Component | `ai-agent` | `rhdh.io/ai-asset-category: agent` | No upstream kind via RFC #32062. Downstream target: `AiResource` / `agent` ([#4164](https://github.com/redhat-developer/rhdh-plugins/pull/4164), merged). Track RHDHPLAN-1113 | Low | |
There was a problem hiding this comment.
we are going with our downstream alternative for 2.1 ... decision made
we will introduce something analogous upstream; if not accepted at all (i.e. there is some talk about not modeling agents as special case kind in the catalog), then we stick with our new type; if a new kind does emerge but is radically different than our original proposal, we'll deal with the migration when the time comes .... again though, this will be dev preview, so if a radical change occurs, breaking level changes are within scope
| Upstream [backstage#34476](https://github.com/backstage/backstage/pull/34476) | ||
| proposes `kind: API` / `spec.type: ai-model-server` — **not** a new | ||
| kind named `ai-model-server`. Migration will be handled if/when the | ||
| upstream PR merges. |
There was a problem hiding this comment.
yes correct ... with details in my prior comments wrt #4211
|
|
||
| | Field | Current | Target | Action | | ||
| | ---------------- | -------------------------------------------------- | ----------------------------- | ------------------------------------------------------------------- | | ||
| | `kind` | `AIResource` (Decision 1 spelling / some emitters) | `AiResource` | Align emitted kind casing to upstream; filters already match either | |
There was a problem hiding this comment.
spelling issue should be fixed from an actual name of the entity kind available .... if a random method field capitalizes the I it is not ethe end of the world, but sure, fix if one is dealing with the code in question
|
|
||
| - Entity refs are unaffected: Backstage lowercases kind in entity ref | ||
| strings, so `airesource:default/my-skill` remains the same whether | ||
| the kind is `AIResource` or `AiResource`. |
There was a problem hiding this comment.
AiResource is the answer
| - Entity refs are unaffected (same lowercasing behavior as skill). | ||
| - Boost runtime already treats `AiResource` as current for filtering. | ||
|
|
||
| ### Model Server (Confidence: Medium/Low) |
There was a problem hiding this comment.
again see comments above .... decision made wrt 2.1 .... AiModelServerAPI
| upstream RFCs. If `AiResource` gains support for bundle semantics, | ||
| casing alignment (same as skill/rule) would apply. | ||
|
|
||
| ### Agent (Confidence: Low) |
There was a problem hiding this comment.
again decision made for 2.1 ....AiResource with the agent type
2 participants
Make OpenSpec
migration-plan.mdthe canonical RHIDP-15302 migration design SoT.workspaces/boost/specifications/ai-asset-upstream-migration-design.md(pointer only; no duplicate tables)migration-readiness/spec.mdandtasks.mdgroup 8Supersedes docs(boost): RHIDP-15302 migration design document (from #4042) #4223 / docs(#4223): RHIDP-15302 migration design document #4225 (do not merge that track).
Naming:
migration-plan.mdunderspecs/next tospec.mdis intentional (design vs Given/When/Then).Part of Upstream Schema Alignment — Annotation Spec, Migration Design & Tooling (issue 4 of 29) #4042