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 6 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 26920 +32
==========================================
+ 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: |
ReviewFindingsHigh
Low
Next steps:
Previous runReviewFindingsMedium
Low
Labels: PR adds documentation under workspaces/boost/openspec/ Next steps:
|
|
/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: |
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 (
|
|



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