{"owner":"react-native-community","repo":"upgrade-helper","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Upgrade Helper — Agent Guide\n\n## Overview\n\nUpgrade Helper is a static web tool that helps developers upgrade React Native applications by showing the full diff between two versions and layering in curated guidance.\n\nThis repository is valuable because it combines:\n\n- upstream template diffs\n- release-specific upgrade notes\n- inline comments on important files\n- binary file download support\n- a simple UI that helps users track upgrade progress\n\nUpgrade Helper is both:\n\n- a trust-sensitive user-facing tool for React Native upgrades\n- an open-source repository that requires steady, low-friction maintenance\n\nTreat both responsibilities seriously. Correctness, stability, and clarity matter more than novelty.\n\n---\n\n## Primary counterpart\n\nYour main human counterpart will often be one of the maintainers of this project.\n\nOptimize for reducing maintainer burden while preserving project quality, trust, and stability.\n\nThat means you should be useful not only for product and code changes, but also for the ongoing work of maintaining an open-source repository, including triage, reproduction, documentation, test hygiene, CI/workflow fixes, and contributor-facing improvements.\n\nWhen context is incomplete, do as much of the legwork as possible before asking for help:\n\n- inspect the relevant code and docs\n- reproduce the issue if possible\n- identify affected files and workflows\n- summarize likely causes\n- propose the smallest safe next step\n\nPrefer giving maintainers ready-to-use output:\n\n- concise issue summaries\n- reproduction notes\n- draft PR descriptions\n- documentation updates\n- focused fix plans\n- validation results\n\n---\n\n## Maintainer support scope\n\nThis agent supports maintainers with both code work and repository maintenance work.\n\nTreat the following as first-class tasks:\n\n- issue triage and bug reproduction\n- narrowing down regressions\n- reviewing contributor changes for risk, correctness, and missing validation\n- improving README, contributing docs, and contributor guidance\n- updating release-specific upgrade content under `src/releases/`\n- maintaining tests, fixtures, mocks, and CI/workflow health\n- identifying small, safe modernization opportunities in an aging codebase\n- preparing clear summaries for maintainers to use in issues, PRs, or discussions\n\nWhen helping with repository maintenance:\n\n- prefer reducing ambiguity for maintainers\n- prefer small, reviewable changes\n- surface risks, follow-ups, and missing information clearly\n- do not assume maintainers want a broad refactor when a targeted fix will do\n- separate immediate fixes from longer-term cleanup ideas\n\n---\n\n## Product priorities\n\n1. Preserve trust in the upgrade guidance\n2. Keep user-facing behavior stable and predictable\n3. Prefer small, reversible maintenance changes\n4. Keep the app static and client-side\n5. Keep contributor and maintainer workflows lightweight and clear\n\n---\n\n## Technical reality\n\nThis is an older but functioning frontend codebase.\n\nCurrent stack:\n\n- React 18\n- Create React App via `react-app-rewired`\n- TypeScript with `strict: true` and `allowJs: true`\n- Emotion for styling\n- Ant Design for UI components\n- Framer Motion for transitions\n- Yarn 1\n- GitHub Pages deployment\n\nCompatibility notes:\n\n- `.node-version` and GitHub Actions currently target Node 16\n- `mise.toml` declares Node 22 locally\n- do not assume the repo is ready for Node-22-only changes unless you are explicitly modernizing the toolchain\n- use `yarn`, not npm or bun, unless explicitly asked to change package management\n\nThis codebase should be treated as legacy-but-live: stable, useful, and worth improving carefully.\n\n---\n\n## Read first\n\nBefore making significant changes, read:\n\n- `README.md`\n- `CONTRIBUTING.md`\n- `package.json`\n- `src/components/pages/Home.tsx`\n- `src/utils.ts`\n- `src/releases/index.js`\n- `src/releases/types.d.ts`\n\nIf touching UI and diff rendering, also read:\n\n- `src/components/common/DiffViewer.tsx`\n- `src/components/common/Diff/DiffSection.tsx`\n- `src/components/common/Diff/DiffHeader.tsx`\n- `src/__tests__/Home.e2e.spec.ts`\n\nIf touching release guidance, study an existing release file first, for example:\n\n- `src/releases/react-native/0.60.tsx`\n- `src/releases/react-native/0.77.tsx`\n\nIf touching maintainer or contributor workflows, also read:\n\n- `.github/PULL_REQUEST_TEMPLATE.md`\n- `.github/workflows/push.yml`\n- `.github/workflows/deploy.yml`\n\nThen read the files directly relevant to your task.\n\n---\n\n## Architecture map\n\n- `src/components/pages/Home.tsx`\n  - top-level page orchestration\n  - theme toggle\n  - URL state\n  - settings and version selectors\n\n- `src/hooks/fetch-release-versions.ts`\n  - fetches available release versions from upstream repos\n\n- `src/hooks/fetch-diff.ts`\n  - fetches raw diff files and parses them for rendering\n\n- `src/utils.ts`\n  - central URL builders\n  - changelog URL generation\n  - version filtering\n  - app name and package replacement\n  - other shared logic\n\n- `src/releases/`\n  - curated release notes and inline upgrade comments\n  - this is part of the product, not incidental content\n\n- `src/theme/`\n  - light/dark theme tokens\n\n- `src/utils/test-utils.ts`\n  - Puppeteer helpers and mocked network responses for screenshot e2e tests\n\n- `.github/workflows/`\n  - CI and deployment workflows\n\n---\n\n## Working principles\n\n### 1. Preserve trust\n\nDo not invent release guidance, upgrade behavior, or troubleshooting advice.\n\nWhen adding or updating release content, prefer authoritative sources such as:\n\n- official React Native blog posts\n- official changelogs\n- relevant upgrade-support issues\n- upstream release notes for macOS and Windows variants\n\nIf a claim is uncertain, omit it or leave a clear follow-up note instead of guessing.\n\n### 2. Treat URL state as part of the product API\n\nThe app relies on URL parameters and anchor links for deep-linking and restoring state.\n\nBe careful when changing behavior related to:\n\n- `from`\n- `to`\n- `package`\n- `language`\n- `name`\n- hash anchors\n\nPreserve backward compatibility whenever possible.\n\n### 3. Prefer incremental modernization\n\nThis repo is old, but it works.\n\nDo not casually combine product work with major ecosystem migrations such as:\n\n- CRA to Vite, Next, or another build system\n- Yarn to pnpm or bun\n- Emotion to another styling system\n- Ant Design replacement\n\nIf modernization is requested, plan it as a focused effort with clear validation and rollback points.\n\n### 4. Respect upstream data contracts\n\nRelease lists and diff files come from upstream repositories.\n\nIf you change fetching or parsing behavior:\n\n- verify the upstream URL structure\n- update mocks and fixtures\n- validate the loading flow and rendered output\n\nDo not introduce server-side assumptions into this static app unless explicitly asked.\n\n### 5. Treat release metadata as product code\n\nFiles under `src/releases/` are a core part of the user experience.\n\nWhen editing them:\n\n- keep copy concise and actionable\n- link to real sources\n- keep inline comments tightly targeted\n- verify `fileName`, `lineNumber`, and `lineChangeType` against the real diff\n- use existing patterns and the `ReleaseT` structure from `src/releases/types.d.ts`\n\n### 6. Preserve the core upgrade flows\n\nBe careful around these user-facing behaviors:\n\n- selecting current and target versions\n- filtering release candidates\n- switching package or platform (`react-native`, `react-native-macos`, `react-native-windows`)\n- switching RNW language (`cpp`, `cs`)\n- replacing default app name and package in displayed paths and file contents\n- rendering diffs and anchor links\n- binary file download, view, and copy actions\n- done-state tracking\n- dark mode\n\n### 7. Keep styling consistent\n\nUse the existing Emotion + Ant Design approach.\n\nWhen changing UI:\n\n- preserve light and dark mode parity\n- avoid introducing a second styling system\n- avoid unnecessary visual churn in a stable tool\n- prefer clarity and legibility over decorative redesigns\n\n### 8. Optimize for maintainer efficiency\n\nWhen a task can be completed by producing a high-quality summary, reproduction, draft, or targeted fix plan, do that work proactively.\n\nGood maintainer support often looks like:\n\n- narrowing a bug from “something is broken” to a specific file and cause\n- preparing a minimal patch instead of a broad rewrite\n- updating docs while fixing the underlying issue\n- identifying whether a problem belongs in code, content, tests, CI, or upstream dependencies\n\n---\n\n## Change-specific guidance\n\n### Adding or updating release guidance\n\nIf a task is about release notes, comments, or upgrade-specific guidance:\n\n1. read `src/releases/types.d.ts`\n2. read one or two existing release files first\n3. add or edit the appropriate file under `src/releases/<package>/`\n4. update `src/releases/index.js` if needed\n5. verify links and comment targets carefully\n\n### Touching shared utilities\n\n`src/utils.ts` is a hotspot.\n\nIf you change it:\n\n- add or update tests in `src/__tests__/utils.spec.ts`\n- check version filtering behavior\n- check changelog URL behavior\n- check app name and package replacement behavior\n\n### Touching remote fetch logic\n\nIf fetch URLs or parsing rules change:\n\n- update mocks in `src/utils/test-utils.ts`\n- update fixtures if needed\n- validate both happy-path loading and user-visible output\n\n### Touching visible UI\n\nIf the UI changes materially:\n\n- run the app locally with `yarn start`\n- validate the key flows manually\n- run e2e screenshots if practical\n- update snapshots intentionally, not incidentally\n\n### Touching contributor or maintainer workflows\n\nIf changing docs, templates, workflows, or maintenance ergonomics:\n\n- preserve contributor clarity\n- keep CI predictable\n- avoid adding unnecessary process overhead\n- explain the maintainer benefit clearly\n\n---\n\n## Validation\n\nMinimum required before finishing work:\n\n- `yarn lint`\n- `yarn typecheck`\n- `yarn test --runInBand`\n\nFor UI or behavior changes, also do:\n\n- `yarn start`\n- manual validation at `http://localhost:3000`\n\nFor higher-confidence UI changes, use:\n\n- `yarn test-e2e`\n- or `yarn docker-test-e2e`\n\nNotes:\n\n- CI currently covers lint, typecheck, and non-e2e tests\n- screenshot e2e coverage is heavier and local-oriented\n- if snapshots change, explain why\n\n---\n\n## Agent operating loop\n\nFor non-trivial tasks, follow this sequence:\n\n1. Scout\n   - identify the affected user flow\n   - identify the relevant upstream data source\n   - identify the tests that should protect the change\n\n2. Plan\n   - choose the smallest safe change\n   - call out risk areas and compatibility concerns\n\n3. Implement\n   - change the narrowest layer possible\n   - avoid opportunistic rewrites\n\n4. Review\n   - challenge the change for correctness\n   - check edge cases\n   - verify it fits the existing architecture\n\n5. Recover\n   - if old tooling blocks progress, apply the smallest unblock\n   - document broader tech debt separately instead of smuggling in a large migration\n\n---\n\n## Reporting back\n\nWhen summarizing work:\n\n- be concise\n- say what changed\n- say what user flow or maintainer workflow it affects\n- say what risks remain\n- list the exact validation commands run\n\n---\n\n## PR and change hygiene\n\n- keep changes small and focused\n- preserve readable diffs\n- for UI changes, include screenshots or a short visual summary when useful\n- explain motivation, impact, and test plan clearly\n- do not bury risky refactors inside unrelated fixes\n"},"files":{"AGENTS.md":"# Upgrade Helper — Agent Guide\n\n## Overview\n\nUpgrade Helper is a static web tool that helps developers upgrade React Native applications by showing the full diff between two versions and layering in curated guidance.\n\nThis repository is valuable because it combines:\n\n- upstream template diffs\n- release-specific upgrade notes\n- inline comments on important files\n- binary file download support\n- a simple UI that helps users track upgrade progress\n\nUpgrade Helper is both:\n\n- a trust-sensitive user-facing tool for React Native upgrades\n- an open-source repository that requires steady, low-friction maintenance\n\nTreat both responsibilities seriously. Correctness, stability, and clarity matter more than novelty.\n\n---\n\n## Primary counterpart\n\nYour main human counterpart will often be one of the maintainers of this project.\n\nOptimize for reducing maintainer burden while preserving project quality, trust, and stability.\n\nThat means you should be useful not only for product and code changes, but also for the ongoing work of maintaining an open-source repository, including triage, reproduction, documentation, test hygiene, CI/workflow fixes, and contributor-facing improvements.\n\nWhen context is incomplete, do as much of the legwork as possible before asking for help:\n\n- inspect the relevant code and docs\n- reproduce the issue if possible\n- identify affected files and workflows\n- summarize likely causes\n- propose the smallest safe next step\n\nPrefer giving maintainers ready-to-use output:\n\n- concise issue summaries\n- reproduction notes\n- draft PR descriptions\n- documentation updates\n- focused fix plans\n- validation results\n\n---\n\n## Maintainer support scope\n\nThis agent supports maintainers with both code work and repository maintenance work.\n\nTreat the following as first-class tasks:\n\n- issue triage and bug reproduction\n- narrowing down regressions\n- reviewing contributor changes for risk, correctness, and missing validation\n- improving README, contributing docs, and contributor guidance\n- updating release-specific upgrade content under `src/releases/`\n- maintaining tests, fixtures, mocks, and CI/workflow health\n- identifying small, safe modernization opportunities in an aging codebase\n- preparing clear summaries for maintainers to use in issues, PRs, or discussions\n\nWhen helping with repository maintenance:\n\n- prefer reducing ambiguity for maintainers\n- prefer small, reviewable changes\n- surface risks, follow-ups, and missing information clearly\n- do not assume maintainers want a broad refactor when a targeted fix will do\n- separate immediate fixes from longer-term cleanup ideas\n\n---\n\n## Product priorities\n\n1. Preserve trust in the upgrade guidance\n2. Keep user-facing behavior stable and predictable\n3. Prefer small, reversible maintenance changes\n4. Keep the app static and client-side\n5. Keep contributor and maintainer workflows lightweight and clear\n\n---\n\n## Technical reality\n\nThis is an older but functioning frontend codebase.\n\nCurrent stack:\n\n- React 18\n- Create React App via `react-app-rewired`\n- TypeScript with `strict: true` and `allowJs: true`\n- Emotion for styling\n- Ant Design for UI components\n- Framer Motion for transitions\n- Yarn 1\n- GitHub Pages deployment\n\nCompatibility notes:\n\n- `.node-version` and GitHub Actions currently target Node 16\n- `mise.toml` declares Node 22 locally\n- do not assume the repo is ready for Node-22-only changes unless you are explicitly modernizing the toolchain\n- use `yarn`, not npm or bun, unless explicitly asked to change package management\n\nThis codebase should be treated as legacy-but-live: stable, useful, and worth improving carefully.\n\n---\n\n## Read first\n\nBefore making significant changes, read:\n\n- `README.md`\n- `CONTRIBUTING.md`\n- `package.json`\n- `src/components/pages/Home.tsx`\n- `src/utils.ts`\n- `src/releases/index.js`\n- `src/releases/types.d.ts`\n\nIf touching UI and diff rendering, also read:\n\n- `src/components/common/DiffViewer.tsx`\n- `src/components/common/Diff/DiffSection.tsx`\n- `src/components/common/Diff/DiffHeader.tsx`\n- `src/__tests__/Home.e2e.spec.ts`\n\nIf touching release guidance, study an existing release file first, for example:\n\n- `src/releases/react-native/0.60.tsx`\n- `src/releases/react-native/0.77.tsx`\n\nIf touching maintainer or contributor workflows, also read:\n\n- `.github/PULL_REQUEST_TEMPLATE.md`\n- `.github/workflows/push.yml`\n- `.github/workflows/deploy.yml`\n\nThen read the files directly relevant to your task.\n\n---\n\n## Architecture map\n\n- `src/components/pages/Home.tsx`\n  - top-level page orchestration\n  - theme toggle\n  - URL state\n  - settings and version selectors\n\n- `src/hooks/fetch-release-versions.ts`\n  - fetches available release versions from upstream repos\n\n- `src/hooks/fetch-diff.ts`\n  - fetches raw diff files and parses them for rendering\n\n- `src/utils.ts`\n  - central URL builders\n  - changelog URL generation\n  - version filtering\n  - app name and package replacement\n  - other shared logic\n\n- `src/releases/`\n  - curated release notes and inline upgrade comments\n  - this is part of the product, not incidental content\n\n- `src/theme/`\n  - light/dark theme tokens\n\n- `src/utils/test-utils.ts`\n  - Puppeteer helpers and mocked network responses for screenshot e2e tests\n\n- `.github/workflows/`\n  - CI and deployment workflows\n\n---\n\n## Working principles\n\n### 1. Preserve trust\n\nDo not invent release guidance, upgrade behavior, or troubleshooting advice.\n\nWhen adding or updating release content, prefer authoritative sources such as:\n\n- official React Native blog posts\n- official changelogs\n- relevant upgrade-support issues\n- upstream release notes for macOS and Windows variants\n\nIf a claim is uncertain, omit it or leave a clear follow-up note instead of guessing.\n\n### 2. Treat URL state as part of the product API\n\nThe app relies on URL parameters and anchor links for deep-linking and restoring state.\n\nBe careful when changing behavior related to:\n\n- `from`\n- `to`\n- `package`\n- `language`\n- `name`\n- hash anchors\n\nPreserve backward compatibility whenever possible.\n\n### 3. Prefer incremental modernization\n\nThis repo is old, but it works.\n\nDo not casually combine product work with major ecosystem migrations such as:\n\n- CRA to Vite, Next, or another build system\n- Yarn to pnpm or bun\n- Emotion to another styling system\n- Ant Design replacement\n\nIf modernization is requested, plan it as a focused effort with clear validation and rollback points.\n\n### 4. Respect upstream data contracts\n\nRelease lists and diff files come from upstream repositories.\n\nIf you change fetching or parsing behavior:\n\n- verify the upstream URL structure\n- update mocks and fixtures\n- validate the loading flow and rendered output\n\nDo not introduce server-side assumptions into this static app unless explicitly asked.\n\n### 5. Treat release metadata as product code\n\nFiles under `src/releases/` are a core part of the user experience.\n\nWhen editing them:\n\n- keep copy concise and actionable\n- link to real sources\n- keep inline comments tightly targeted\n- verify `fileName`, `lineNumber`, and `lineChangeType` against the real diff\n- use existing patterns and the `ReleaseT` structure from `src/releases/types.d.ts`\n\n### 6. Preserve the core upgrade flows\n\nBe careful around these user-facing behaviors:\n\n- selecting current and target versions\n- filtering release candidates\n- switching package or platform (`react-native`, `react-native-macos`, `react-native-windows`)\n- switching RNW language (`cpp`, `cs`)\n- replacing default app name and package in displayed paths and file contents\n- rendering diffs and anchor links\n- binary file download, view, and copy actions\n- done-state tracking\n- dark mode\n\n### 7. Keep styling consistent\n\nUse the existing Emotion + Ant Design approach.\n\nWhen changing UI:\n\n- preserve light and dark mode parity\n- avoid introducing a second styling system\n- avoid unnecessary visual churn in a stable tool\n- prefer clarity and legibility over decorative redesigns\n\n### 8. Optimize for maintainer efficiency\n\nWhen a task can be completed by producing a high-quality summary, reproduction, draft, or targeted fix plan, do that work proactively.\n\nGood maintainer support often looks like:\n\n- narrowing a bug from “something is broken” to a specific file and cause\n- preparing a minimal patch instead of a broad rewrite\n- updating docs while fixing the underlying issue\n- identifying whether a problem belongs in code, content, tests, CI, or upstream dependencies\n\n---\n\n## Change-specific guidance\n\n### Adding or updating release guidance\n\nIf a task is about release notes, comments, or upgrade-specific guidance:\n\n1. read `src/releases/types.d.ts`\n2. read one or two existing release files first\n3. add or edit the appropriate file under `src/releases/<package>/`\n4. update `src/releases/index.js` if needed\n5. verify links and comment targets carefully\n\n### Touching shared utilities\n\n`src/utils.ts` is a hotspot.\n\nIf you change it:\n\n- add or update tests in `src/__tests__/utils.spec.ts`\n- check version filtering behavior\n- check changelog URL behavior\n- check app name and package replacement behavior\n\n### Touching remote fetch logic\n\nIf fetch URLs or parsing rules change:\n\n- update mocks in `src/utils/test-utils.ts`\n- update fixtures if needed\n- validate both happy-path loading and user-visible output\n\n### Touching visible UI\n\nIf the UI changes materially:\n\n- run the app locally with `yarn start`\n- validate the key flows manually\n- run e2e screenshots if practical\n- update snapshots intentionally, not incidentally\n\n### Touching contributor or maintainer workflows\n\nIf changing docs, templates, workflows, or maintenance ergonomics:\n\n- preserve contributor clarity\n- keep CI predictable\n- avoid adding unnecessary process overhead\n- explain the maintainer benefit clearly\n\n---\n\n## Validation\n\nMinimum required before finishing work:\n\n- `yarn lint`\n- `yarn typecheck`\n- `yarn test --runInBand`\n\nFor UI or behavior changes, also do:\n\n- `yarn start`\n- manual validation at `http://localhost:3000`\n\nFor higher-confidence UI changes, use:\n\n- `yarn test-e2e`\n- or `yarn docker-test-e2e`\n\nNotes:\n\n- CI currently covers lint, typecheck, and non-e2e tests\n- screenshot e2e coverage is heavier and local-oriented\n- if snapshots change, explain why\n\n---\n\n## Agent operating loop\n\nFor non-trivial tasks, follow this sequence:\n\n1. Scout\n   - identify the affected user flow\n   - identify the relevant upstream data source\n   - identify the tests that should protect the change\n\n2. Plan\n   - choose the smallest safe change\n   - call out risk areas and compatibility concerns\n\n3. Implement\n   - change the narrowest layer possible\n   - avoid opportunistic rewrites\n\n4. Review\n   - challenge the change for correctness\n   - check edge cases\n   - verify it fits the existing architecture\n\n5. Recover\n   - if old tooling blocks progress, apply the smallest unblock\n   - document broader tech debt separately instead of smuggling in a large migration\n\n---\n\n## Reporting back\n\nWhen summarizing work:\n\n- be concise\n- say what changed\n- say what user flow or maintainer workflow it affects\n- say what risks remain\n- list the exact validation commands run\n\n---\n\n## PR and change hygiene\n\n- keep changes small and focused\n- preserve readable diffs\n- for UI changes, include screenshots or a short visual summary when useful\n- explain motivation, impact, and test plan clearly\n- do not bury risky refactors inside unrelated fixes\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Upgrade Helper — Agent Guide\n\n## Overview\n\nUpgrade Helper is a static web tool that helps developers upgrade React Native applications by showing the full diff between two versions and layering in curated guidance.\n\nThis repository is valuable because it combines:\n\n- upstream template diffs\n- release-specific upgrade notes\n- inline comments on important files\n- binary file download support\n- a simple UI that helps users track upgrade progress\n\nUpgrade Helper is both:\n\n- a trust-sensitive user-facing tool for React Native upgrades\n- an open-source repository that requires steady, low-friction maintenance\n\nTreat both responsibilities seriously. Correctness, stability, and clarity matter more than novelty.\n\n---\n\n## Primary counterpart\n\nYour main human counterpart will often be one of the maintainers of this project.\n\nOptimize for reducing maintainer burden while preserving project quality, trust, and stability.\n\nThat means you should be useful not only for product and code changes, but also for the ongoing work of maintaining an open-source repository, including triage, reproduction, documentation, test hygiene, CI/workflow fixes, and contributor-facing improvements.\n\nWhen context is incomplete, do as much of the legwork as possible before asking for help:\n\n- inspect the relevant code and docs\n- reproduce the issue if possible\n- identify affected files and workflows\n- summarize likely causes\n- propose the smallest safe next step\n\nPrefer giving maintainers ready-to-use output:\n\n- concise issue summaries\n- reproduction notes\n- draft PR descriptions\n- documentation updates\n- focused fix plans\n- validation results\n\n---\n\n## Maintainer support scope\n\nThis agent supports maintainers with both code work and repository maintenance work.\n\nTreat the following as first-class tasks:\n\n- issue triage and bug reproduction\n- narrowing down regressions\n- reviewing contributor changes for risk, correctness, and missing validation\n- improving README, contributing docs, and contributor guidance\n- updating release-specific upgrade content under `src/releases/`\n- maintaining tests, fixtures, mocks, and CI/workflow health\n- identifying small, safe modernization opportunities in an aging codebase\n- preparing clear summaries for maintainers to use in issues, PRs, or discussions\n\nWhen helping with repository maintenance:\n\n- prefer reducing ambiguity for maintainers\n- prefer small, reviewable changes\n- surface risks, follow-ups, and missing information clearly\n- do not assume maintainers want a broad refactor when a targeted fix will do\n- separate immediate fixes from longer-term cleanup ideas\n\n---\n\n## Product priorities\n\n1. Preserve trust in the upgrade guidance\n2. Keep user-facing behavior stable and predictable\n3. Prefer small, reversible maintenance changes\n4. Keep the app static and client-side\n5. Keep contributor and maintainer workflows lightweight and clear\n\n---\n\n## Technical reality\n\nThis is an older but functioning frontend codebase.\n\nCurrent stack:\n\n- React 18\n- Create React App via `react-app-rewired`\n- TypeScript with `strict: true` and `allowJs: true`\n- Emotion for styling\n- Ant Design for UI components\n- Framer Motion for transitions\n- Yarn 1\n- GitHub Pages deployment\n\nCompatibility notes:\n\n- `.node-version` and GitHub Actions currently target Node 16\n- `mise.toml` declares Node 22 locally\n- do not assume the repo is ready for Node-22-only changes unless you are explicitly modernizing the toolchain\n- use `yarn`, not npm or bun, unless explicitly asked to change package management\n\nThis codebase should be treated as legacy-but-live: stable, useful, and worth improving carefully.\n\n---\n\n## Read first\n\nBefore making significant changes, read:\n\n- `README.md`\n- `CONTRIBUTING.md`\n- `package.json`\n- `src/components/pages/Home.tsx`\n- `src/utils.ts`\n- `src/releases/index.js`\n- `src/releases/types.d.ts`\n\nIf touching UI and diff rendering, also read:\n\n- `src/components/common/DiffViewer.tsx`\n- `src/components/common/Diff/DiffSection.tsx`\n- `src/components/common/Diff/DiffHeader.tsx`\n- `src/__tests__/Home.e2e.spec.ts`\n\nIf touching release guidance, study an existing release file first, for example:\n\n- `src/releases/react-native/0.60.tsx`\n- `src/releases/react-native/0.77.tsx`\n\nIf touching maintainer or contributor workflows, also read:\n\n- `.github/PULL_REQUEST_TEMPLATE.md`\n- `.github/workflows/push.yml`\n- `.github/workflows/deploy.yml`\n\nThen read the files directly relevant to your task.\n\n---\n\n## Architecture map\n\n- `src/components/pages/Home.tsx`\n  - top-level page orchestration\n  - theme toggle\n  - URL state\n  - settings and version selectors\n\n- `src/hooks/fetch-release-versions.ts`\n  - fetches available release versions from upstream repos\n\n- `src/hooks/fetch-diff.ts`\n  - fetches raw diff files and parses them for rendering\n\n- `src/utils.ts`\n  - central URL builders\n  - changelog URL generation\n  - version filtering\n  - app name and package replacement\n  - other shared logic\n\n- `src/releases/`\n  - curated release notes and inline upgrade comments\n  - this is part of the product, not incidental content\n\n- `src/theme/`\n  - light/dark theme tokens\n\n- `src/utils/test-utils.ts`\n  - Puppeteer helpers and mocked network responses for screenshot e2e tests\n\n- `.github/workflows/`\n  - CI and deployment workflows\n\n---\n\n## Working principles\n\n### 1. Preserve trust\n\nDo not invent release guidance, upgrade behavior, or troubleshooting advice.\n\nWhen adding or updating release content, prefer authoritative sources such as:\n\n- official React Native blog posts\n- official changelogs\n- relevant upgrade-support issues\n- upstream release notes for macOS and Windows variants\n\nIf a claim is uncertain, omit it or leave a clear follow-up note instead of guessing.\n\n### 2. Treat URL state as part of the product API\n\nThe app relies on URL parameters and anchor links for deep-linking and restoring state.\n\nBe careful when changing behavior related to:\n\n- `from`\n- `to`\n- `package`\n- `language`\n- `name`\n- hash anchors\n\nPreserve backward compatibility whenever possible.\n\n### 3. Prefer incremental modernization\n\nThis repo is old, but it works.\n\nDo not casually combine product work with major ecosystem migrations such as:\n\n- CRA to Vite, Next, or another build system\n- Yarn to pnpm or bun\n- Emotion to another styling system\n- Ant Design replacement\n\nIf modernization is requested, plan it as a focused effort with clear validation and rollback points.\n\n### 4. Respect upstream data contracts\n\nRelease lists and diff files come from upstream repositories.\n\nIf you change fetching or parsing behavior:\n\n- verify the upstream URL structure\n- update mocks and fixtures\n- validate the loading flow and rendered output\n\nDo not introduce server-side assumptions into this static app unless explicitly asked.\n\n### 5. Treat release metadata as product code\n\nFiles under `src/releases/` are a core part of the user experience.\n\nWhen editing them:\n\n- keep copy concise and actionable\n- link to real sources\n- keep inline comments tightly targeted\n- verify `fileName`, `lineNumber`, and `lineChangeType` against the real diff\n- use existing patterns and the `ReleaseT` structure from `src/releases/types.d.ts`\n\n### 6. Preserve the core upgrade flows\n\nBe careful around these user-facing behaviors:\n\n- selecting current and target versions\n- filtering release candidates\n- switching package or platform (`react-native`, `react-native-macos`, `react-native-windows`)\n- switching RNW language (`cpp`, `cs`)\n- replacing default app name and package in displayed paths and file contents\n- rendering diffs and anchor links\n- binary file download, view, and copy actions\n- done-state tracking\n- dark mode\n\n### 7. Keep styling consistent\n\nUse the existing Emotion + Ant Design approach.\n\nWhen changing UI:\n\n- preserve light and dark mode parity\n- avoid introducing a second styling system\n- avoid unnecessary visual churn in a stable tool\n- prefer clarity and legibility over decorative redesigns\n\n### 8. Optimize for maintainer efficiency\n\nWhen a task can be completed by producing a high-quality summary, reproduction, draft, or targeted fix plan, do that work proactively.\n\nGood maintainer support often looks like:\n\n- narrowing a bug from “something is broken” to a specific file and cause\n- preparing a minimal patch instead of a broad rewrite\n- updating docs while fixing the underlying issue\n- identifying whether a problem belongs in code, content, tests, CI, or upstream dependencies\n\n---\n\n## Change-specific guidance\n\n### Adding or updating release guidance\n\nIf a task is about release notes, comments, or upgrade-specific guidance:\n\n1. read `src/releases/types.d.ts`\n2. read one or two existing release files first\n3. add or edit the appropriate file under `src/releases/<package>/`\n4. update `src/releases/index.js` if needed\n5. verify links and comment targets carefully\n\n### Touching shared utilities\n\n`src/utils.ts` is a hotspot.\n\nIf you change it:\n\n- add or update tests in `src/__tests__/utils.spec.ts`\n- check version filtering behavior\n- check changelog URL behavior\n- check app name and package replacement behavior\n\n### Touching remote fetch logic\n\nIf fetch URLs or parsing rules change:\n\n- update mocks in `src/utils/test-utils.ts`\n- update fixtures if needed\n- validate both happy-path loading and user-visible output\n\n### Touching visible UI\n\nIf the UI changes materially:\n\n- run the app locally with `yarn start`\n- validate the key flows manually\n- run e2e screenshots if practical\n- update snapshots intentionally, not incidentally\n\n### Touching contributor or maintainer workflows\n\nIf changing docs, templates, workflows, or maintenance ergonomics:\n\n- preserve contributor clarity\n- keep CI predictable\n- avoid adding unnecessary process overhead\n- explain the maintainer benefit clearly\n\n---\n\n## Validation\n\nMinimum required before finishing work:\n\n- `yarn lint`\n- `yarn typecheck`\n- `yarn test --runInBand`\n\nFor UI or behavior changes, also do:\n\n- `yarn start`\n- manual validation at `http://localhost:3000`\n\nFor higher-confidence UI changes, use:\n\n- `yarn test-e2e`\n- or `yarn docker-test-e2e`\n\nNotes:\n\n- CI currently covers lint, typecheck, and non-e2e tests\n- screenshot e2e coverage is heavier and local-oriented\n- if snapshots change, explain why\n\n---\n\n## Agent operating loop\n\nFor non-trivial tasks, follow this sequence:\n\n1. Scout\n   - identify the affected user flow\n   - identify the relevant upstream data source\n   - identify the tests that should protect the change\n\n2. Plan\n   - choose the smallest safe change\n   - call out risk areas and compatibility concerns\n\n3. Implement\n   - change the narrowest layer possible\n   - avoid opportunistic rewrites\n\n4. Review\n   - challenge the change for correctness\n   - check edge cases\n   - verify it fits the existing architecture\n\n5. Recover\n   - if old tooling blocks progress, apply the smallest unblock\n   - document broader tech debt separately instead of smuggling in a large migration\n\n---\n\n## Reporting back\n\nWhen summarizing work:\n\n- be concise\n- say what changed\n- say what user flow or maintainer workflow it affects\n- say what risks remain\n- list the exact validation commands run\n\n---\n\n## PR and change hygiene\n\n- keep changes small and focused\n- preserve readable diffs\n- for UI changes, include screenshots or a short visual summary when useful\n- explain motivation, impact, and test plan clearly\n- do not bury risky refactors inside unrelated fixes\n","category":"root","tokens":2848}]}