Skip to content

docs(#4042): add migration design document for upstream entity kinds - #4221

Open
fullsend-ai-coder[bot] wants to merge 6 commits into
mainfrom
agent/4042-migration-design-doc
Open

docs(#4042): add migration design document for upstream entity kinds#4221
fullsend-ai-coder[bot] wants to merge 6 commits into
mainfrom
agent/4042-migration-design-doc

Conversation

@fullsend-ai-coder

@fullsend-ai-coder fullsend-ai-coder Bot commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Make OpenSpec migration-plan.md the canonical RHIDP-15302 migration design SoT.

@fullsend-ai-coder fullsend-ai-coder Bot added the ready-for-review Agent PR ready for human review label Aug 10, 2026
@codecov

codecov Bot commented Aug 10, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 58.38%. Comparing base (50cec85) to head (69ff636).
⚠️ Report is 5 commits behind head on main.
✅ All tests successful. No failed tests found.

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              
Flag Coverage Δ *Carryforward flag
adoption-insights 84.55% <ø> (ø) Carriedforward from b56ca4b
ai-integrations 69.16% <ø> (ø) Carriedforward from b56ca4b
app-defaults 69.79% <ø> (ø) Carriedforward from b56ca4b
augment 46.67% <ø> (ø) Carriedforward from b56ca4b
boost 77.63% <ø> (+0.85%) ⬆️
bulk-import 72.79% <ø> (ø) Carriedforward from b56ca4b
cost-management 13.55% <ø> (ø) Carriedforward from b56ca4b
dcm 67.21% <ø> (ø) Carriedforward from b56ca4b
extensions 56.59% <ø> (ø) Carriedforward from b56ca4b
global-floating-action-button 71.18% <ø> (ø) Carriedforward from b56ca4b
global-header 66.50% <ø> (ø) Carriedforward from b56ca4b
homepage 47.50% <ø> (ø) Carriedforward from b56ca4b
install-dynamic-plugins 59.95% <ø> (ø) Carriedforward from b56ca4b
intelligent-assistant 75.24% <ø> (ø) Carriedforward from b56ca4b
konflux 91.98% <ø> (ø) Carriedforward from b56ca4b
lightspeed 69.02% <ø> (ø) Carriedforward from b56ca4b
mcp-integrations 83.40% <ø> (ø) Carriedforward from b56ca4b
orchestrator 66.91% <ø> (ø) Carriedforward from b56ca4b
quickstart 63.74% <ø> (ø) Carriedforward from b56ca4b
sandbox 79.56% <ø> (ø) Carriedforward from b56ca4b
scorecard 86.17% <ø> (ø) Carriedforward from b56ca4b
theme 88.77% <ø> (ø) Carriedforward from b56ca4b
translations 5.12% <ø> (ø) Carriedforward from b56ca4b
x2a 79.20% <ø> (ø) Carriedforward from b56ca4b

*This pull request uses carry forward flags. Click here to find out more.


Continue to review full report in Codecov by Harness.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 50cec85...69ff636. Read the comment docs.

🚀 New features to boost your workflow:
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@mareklibra

Copy link
Copy Markdown
Member

/fs-fix CI issues (prettier)

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 10, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 9:41 AM UTC · Completed 9:52 AM UTC

Commit: 5c01fa0 · View workflow run →

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 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):

  1. CI prettier check failing on migration design document (workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/design.md): Ran prettier to fix markdown table alignment and italic marker formatting (text -> text) that caused CI prettier:check to fail

Tests: passed

Updated by fullsend fix agent

fullsend-ai-coder Bot added a commit that referenced this pull request Aug 10, 2026
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
@mareklibra

Copy link
Copy Markdown
Member

/fs-review

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 10, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 9:58 AM UTC · Completed 10:15 AM UTC

Commit: 8441a3f · View workflow run →

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 10, 2026

Copy link
Copy Markdown

Review

Findings

High

  • [naming-convention] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md — File named migration-plan.md in a specs/ subdirectory, breaking the universal convention. Every other markdown file across all 67+ specs/ subdirectories (across 18 change directories) is named spec.md. The existing spec.md in the same migration-readiness/ directory already covers migration readiness requirements. Additionally, AGENTS.md describes specs/ directories as containing "Behavioral specs (Given/When/Then)", while this document is a design/readiness document, not a behavioral spec — raising the question of whether it belongs in specs/ at all or should live alongside design.md at the change root.
    Remediation: Rename migration-plan.md to spec.md (if it replaces the existing spec.md), merge content into the existing spec.md, place it in a new subdirectory (e.g., specs/migration-plan/spec.md), or move it to the change root alongside design.md since it is a design document rather than a behavioral spec.

Low

  • [internal-consistency] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md — Minor inconsistency between the Consumer-Facing Changes Catalog UI Filters table and the Backward Compatibility Strategy section regarding skill/rule kind casing changes. The Catalog UI Filters table (Impact column for skill and rule) states "Update kind filter casing," implying consumers need to take action. However, the Backward Compatibility Strategy section states: "Backstage catalog kind matching is case-insensitive, so existing kind=AIResource filters continue to work after casing alignment." These give conflicting guidance — one says update your filters, the other says no update is needed.
    Remediation: Align the Catalog UI Filters table impact column for skill and rule with the backward compat section — e.g., "Casing alignment only. Existing kind=AIResource filters continue to work (case-insensitive matching). Update filter casing for naming consistency when convenient."

Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR
Previous run

Review

Findings

Medium

  • [internal consistency / edge case correctness] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/design.md:312 — The Dual-Filter Period section claims both old and new query patterns work during release N, showing the old pattern as filter=kind=Resource,rhdh.io/ai-asset-category=model-server. However, the Migration Execution Strategy (lines 296–304) states the catalog processor applies kind transformations during entity refresh, changing model-server entities from kind: Resource to kind: API. A query filtering by kind=Resource will not match an entity whose kind has been changed to API, regardless of annotation retention. Backstage catalog filter terms are AND conditions, so the combined old pattern fails even though the annotation is retained. The backward compatibility guarantee does not hold for kind-change migrations (model-server).
    Remediation: Either (a) change the example old pattern to omit the kind filter (e.g., ?filter=rhdh.io/ai-asset-category=model-server), (b) document that dual-filter backward compatibility applies only to casing-change migrations (skill, rule) and not to kind-change migrations (model-server: Resource→API), or (c) describe a mechanism (e.g., dual entity emission or catalog processor alias) that would make both patterns work.

  • [file placement / naming convention] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/design.md — This is the only design.md file placed inside a specs/<name>/ subdirectory across the entire openspec/changes/ tree. All 18 existing change directories place design.md at the change level (changes/<change-name>/design.md); spec subdirectories contain only spec.md. This breaks the established file-type-to-location convention.
    Remediation: Consider (a) merging the migration design content into the parent ai-catalog-entity-model/design.md as a new section, (b) creating a top-level change directory (e.g., changes/migration-readiness/design.md), or (c) renaming the file to something other than design.md (e.g., migration-plan.md) to avoid collision with the change-level naming convention.

  • [scope-vs-authorization] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/design.md — The PR uses Closes #4042 but issue acceptance criterion 8.5 requires obtaining RHDH architect/tech-lead sign-off, and the sign-off table in the document is still "Pending". Auto-closing the issue on merge would leave an unfulfilled acceptance criterion.
    Remediation: Either (a) remove Closes #4042 and replace with Part of #4042 so the issue stays open until sign-off is recorded, (b) obtain and record the sign-off before merge, or (c) update the issue to clarify that sign-off can be recorded post-merge via a follow-up commit.

Low

  • [heading convention] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/design.md:1 — The H1 heading uses # Migration Design: RHDH AI-Asset Entities to Upstream Backstage Kinds while all existing design.md files use the format # Design: <Title>.
    Remediation: Rename to # Design: Migration Readiness for Upstream Entity Kinds.

  • [document structure convention] workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/design.md — The document uses a custom section structure instead of the established ## Context## Goals## Non-Goals## Decisions## Risks skeleton used by all other design.md files. The document's purpose (migration mapping) may justify some deviation, but the complete departure reduces cross-document navigability.
    Remediation: Consider restructuring to follow the established skeleton where appropriate (e.g., frame mapping table and transformation rules as ## Decisions subsections, add ## Context and ## Risks sections).


Labels: PR adds documentation under workspaces/boost/openspec/


Next steps:

  • /fs-fix — agent addresses review findings automatically
  • /fs-fix <your instruction> — agent fixes with your specific guidance
  • Push commits directly — review re-runs automatically on push
  • /fs-fix-stop — disable automatic fix runs for this PR

fullsend-ai-review[bot]

This comment was marked as outdated.

@fullsend-ai-review fullsend-ai-review Bot added documentation Improvements or additions to documentation workspace/boost Boost workspace (Backstage AI plugin) Review effort 1/5 labels Aug 10, 2026
@mareklibra

Copy link
Copy Markdown
Member

/fs-fix Address open review findings on this docs PR. Keep content accurate; do not invent new migration mechanisms.

Must fix (correctness / process):

  1. Backward-compat dual-filter is wrong for kind-change migrations (design.md Dual-Filter Period ~L293–308, and the broader claims in Annotation Retention ~L264–268 and Deprecation Timeline ~L272–274).

    • Today the “old” example is ?filter=kind=Resource,rhdh.io/ai-asset-category=model-server, but Migration Execution Strategy says the processor changes model-server from kind: Resourcekind: API. Catalog filters AND within a set, so that old pattern does not match after migration even if the annotation is retained.
    • Fix by doing all of:
      • Change the Dual-Filter “old” example to annotation-only using the full Backstage path: ?filter=metadata.annotations.rhdh.io/ai-asset-category=model-server (and prefer that full path anywhere this doc shows annotation filters; neo4j OpenSpec already uses metadata.annotations.rhdh.io/ai-asset-category).
      • Explicitly state that annotation retention supports annotation-based queries during release N; it does not make pre-migration kind filters work after a kind change (ResourceAPI for model-server).
      • Note that skill/rule casing (AIResourceAiResource) is different: catalog kind matching is case-insensitive, so kind casing alone is not a dual-filter problem.
    • Do not invent dual-entity emission / alias processors unless already decided elsewhere—document the limitation instead.
  2. Entity-ref / relationship caveat (Migration Execution Strategy ~L283–287). Soften or correct the claim that “the catalog handles ref format changes when the entity kind changes.” Clarify that the migrated entity’s own ref changes (resource:api: for model-server), but inbound relationships / hardcoded refs in other entities are not auto-rewritten and need an explicit migration plan (call out as future work if needed).

Must fix (convention):

  1. File placement: This is the only design.md under openspec/changes/**/specs/** (all other specs/ trees have only spec.md; change-level design.md uses # Design: …). Prefer the least-disruptive fix: rename specs/migration-readiness/design.mdspecs/migration-readiness/migration-plan.md (keep it next to spec.md), update relative links/references, and set H1 to something like # Migration Plan: RHDH AI-Asset Entities to Upstream Backstage Kinds. Do not create a new top-level change directory unless renaming is blocked.

Should fix (light polish):

  1. If the file remains named design.md for any reason, rename H1 to # Design: Migration Readiness for Upstream Entity Kinds. (If renamed to migration-plan.md per build(deps): bump webpack from 5.91.0 to 5.95.0 #4, the Migration Plan H1 is fine.)
  2. Optionally add brief ## Context / ## Risks sections (or a short pointer) so the doc is easier to navigate next to other OpenSpec designs—do not force a full rewrite into Goals/Non-Goals/Decisions if it hurts readability of the mapping tables.

Already done — skip: prettier formatting (commit 8441a3f).

Out of scope for this fix: obtaining real architect sign-off; implementing CLI/annotation publish (#4220); executing migration.

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 10, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 10:33 AM UTC · Completed 10:42 AM UTC

Commit: 8441a3f · View workflow run →

@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 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):

  1. Backward-compat dual-filter wrong for kind-change migrations (workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md): Changed Dual-Filter old example to annotation-only using full Backstage path metadata.annotations.rhdh.io/ai-asset-category=model-server. Updated Annotation Retention to explicitly state it supports annotation-based queries only, not pre-migration kind filters after a kind change. Added Limitation paragraph and Note block explaining the AND semantics. Added casing-only caveat (AIResource to AiResource is case-insensitive, not a dual-filter problem). Updated API Queries table model-server current query to use full annotation path. Did not invent dual-entity emission or alias processors.
  2. Entity-ref / relationship caveat incorrect (workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md): Softened Migration Execution Strategy item 2: clarified migrated entity own ref updates as consequence of kind change, but inbound relationships and hardcoded refs in other entities are NOT automatically rewritten. Updated Entity References table model-server impact text to note inbound refs are not auto-rewritten. Added Inbound ref migration plan to Future Work section.
  3. File placement convention: design.md in specs/ tree (workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md): Renamed design.md to migration-plan.md (keeping it next to spec.md). Updated H1 to Migration Plan: RHDH AI-Asset Entities to Upstream Backstage Kinds. No other files referenced migration-readiness/design.md, so no link updates needed.
  4. H1 naming convention (conditional on rename) (workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md): Since file was renamed to migration-plan.md per finding 4, H1 set to Migration Plan title which is the appropriate title per the reviewer instruction.
  5. Add Context / Risks sections for navigability (workspaces/boost/openspec/changes/ai-catalog-entity-model/specs/migration-readiness/migration-plan.md): Added brief Context section summarizing why this plan exists and listing key inputs. Added Risks section covering upstream PR rejection risk, inbound relationship breakage, kind-filter breakage during transition, and agent kind uncertainty.

Tests: passed

Updated by fullsend fix agent

fullsend-ai-coder Bot added a commit that referenced this pull request Aug 10, 2026
- 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
@mareklibra

Copy link
Copy Markdown
Member

/fs-fix CI issues (prettier)

@fullsend-ai-coder

fullsend-ai-coder Bot commented Aug 10, 2026

Copy link
Copy Markdown
Contributor Author

🤖 Finished Fix · ✅ Success · Started 11:02 AM UTC · Completed 11:13 AM UTC

Commit: f34dd2a · View workflow run →

fullsend-ai-coder Bot added a commit that referenced this pull request Aug 10, 2026
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
@fullsend-ai-coder

Copy link
Copy Markdown
Contributor Author

🔧 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):

  1. CI prettier formatting failure on migration-plan.md: Ran prettier --write from the boost workspace to normalize markdown table column widths in the Entity References and API Queries tables. The model-server row determined the max column width; prettier trimmed trailing spaces on shorter rows and expanded the API Queries Current Query column to accommodate the full-width model-server row.

Tests: passed

Updated by fullsend fix agent

@mareklibra

Copy link
Copy Markdown
Member

/fs-review

@fullsend-ai-review

fullsend-ai-review Bot commented Aug 10, 2026

Copy link
Copy Markdown

🤖 Finished Review · ✅ Success · Started 11:19 AM UTC · Completed 11:35 AM UTC

Commit: 2be09b4 · View workflow run →

@fullsend-ai-review fullsend-ai-review Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See the review comment for full details.

fullsend-ai-coder Bot and others added 5 commits August 10, 2026 14:07
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
@mareklibra
mareklibra force-pushed the agent/4042-migration-design-doc branch from 06e8a67 to b56ca4b Compare August 10, 2026 12:07
Make OpenSpec migration-plan.md the explicit RHIDP-15302 design SoT
via cross-links from spec.md and tasks.md, and add a thin
specifications/ pointer for platform-engineer discoverability without
duplicating mapping tables. Supersedes the parallel #4223/#4225 track.
Part of #4042
@mareklibra

mareklibra commented Aug 10, 2026

Copy link
Copy Markdown
Member

@gabemontero — please LGTM this as the canonical RHIDP-15302 design SoT (migration-plan.md).

@sonarqubecloud

Copy link
Copy Markdown

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation ready-for-review Agent PR ready for human review Review effort 1/5 workspace/boost Boost workspace (Backstage AI plugin)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant