From 8a9786cf970e89d03c3616a7538be681f9b39884 Mon Sep 17 00:00:00 2001 From: fullsend-code <278716306+fullsend-ai-coder[bot]@users.noreply.github.com> Date: Tue, 11 Aug 2026 23:28:46 +0000 Subject: [PATCH] docs(#4263): add upstream-tracking convention to AGENTS.md Add an "Upstream-Tracking Packages" section to the ai-integrations workspace AGENTS.md documenting that some packages replicate upstream backstage/backstage schemas as stopgaps while upstream PRs are pending. When a package explicitly tracks an upstream PR, upstream naming and API conventions (interface names, apiVersion typing, type guard patterns, moduleId format) take precedence over workspace-local conventions. This prevents review agents from flagging intentional upstream alignment as convention violations, reducing false positive findings on upstream-tracking PRs. Closes #4263 Assisted-by: Claude Opus 4.6 Co-Authored-By: Claude Opus 4.6 --- workspaces/ai-integrations/AGENTS.md | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/workspaces/ai-integrations/AGENTS.md b/workspaces/ai-integrations/AGENTS.md index 43ad33060e..738bd4d2b3 100644 --- a/workspaces/ai-integrations/AGENTS.md +++ b/workspaces/ai-integrations/AGENTS.md @@ -110,6 +110,34 @@ function safeGetOptionalString( } ``` +## Upstream-Tracking Packages + +Some packages in this workspace replicate upstream `backstage/backstage` +schemas as stopgaps while the corresponding upstream PRs are pending. +These packages reference the upstream PR (e.g., `backstage/backstage#34476`) +in their changeset description or linked issue. + +When a package explicitly tracks an upstream PR, upstream naming and API +conventions take precedence over workspace-local conventions. This includes: + +- **Interface names** — upstream names are used as-is, even if they omit a + version suffix (e.g., `AiModelServerApiEntity` instead of + `AgentAiResourceEntityV1alpha1`) +- **`apiVersion` typing** — may use a broad `string` type instead of a + pinned literal union, matching the upstream schema +- **Type guard patterns** — may omit `apiVersion` checks when the upstream + pattern relies on dedicated kinds alone +- **`moduleId` format** — uses the upstream short form (e.g., + `'ai-model-server'`) matching the upstream convention (e.g., `'ai-model'`) + +Do not flag convention deviations in upstream-tracking packages when the +deviation matches the cited upstream code. These are intentional for +migration parity and will be reconciled when the upstream PR merges. + +The upstream PR number must be documented in the changeset description or +linked issue so reviewers (human and automated) can verify the upstream +alignment. + ## PR Conventions - All commits must have an `Assisted-by: ` footer below the sign offs