diff --git a/skills/upgrade-optics/SKILL.md b/skills/upgrade-optics/SKILL.md new file mode 100644 index 0000000..a3c4903 --- /dev/null +++ b/skills/upgrade-optics/SKILL.md @@ -0,0 +1,156 @@ +--- +name: upgrade-optics +description: Upgrade @rolemodel/optics to a target version. Reviews release notes for every intermediate version, audits the codebase for breaking changes, implements all required fixes, verifies the CSS build, and optionally opens a PR. +metadata: + triggers: + - upgrade optics + - update optics + - optics version +--- + +## Steps + +### 1. Identify current and target versions + +Check `package.json` for the current `@rolemodel/optics` version. The user will supply the target version; if not, use the latest (`gh release list --repo RoleModel/optics --limit 1`). + +### 2. Choose an upgrade mode + +Ask the user: + +> There are X versions between your current version and the target. Would you like to: +> - **Release by release** — step through each version one at a time. After each one, you can open a PR and give the green light before the next version begins. +> - **All at once** — upgrade straight to the target in one pass, then optionally open a single PR for all the work. + +--- + +## Mode A: Release by release + +Repeat the following cycle for each version in order. + +### A1. Fetch release notes for the next version + +```bash +gh release view --repo RoleModel/optics +``` + +Present a summary of what changed. Flag anything under headings like **Component Changes**, **Base Token Changes**, **Layout Changes**, **Distribution Changes**, or **Breaking**. Note additive-only releases as low-risk. + +### A2. Audit the codebase against this version's changes + +For each flagged change, derive what to search for from the release note itself. The goal is to find every place the app touches the changed behaviour. + +General approach: +1. Identify what the app would have to be doing to be affected (e.g. using a renamed token, importing a path that moved, overriding a property that no longer exists). +2. Search broadly — not just stylesheets. Optics class names and tokens can appear in many places depending on the stack: + - **Rails views** (`.slim`, `.erb`) — hardcoded class names, icon font classes, inline style attributes + - **React components** (`.jsx`, `.tsx`) — `className` strings, CSS module references, inline style objects using token values + - **Web components** — CSS custom properties (tokens) are the primary styling vector through shadow DOM; a renamed token silently stops applying inside any shadow root that references it + - **Spec files** (RSpec, Capybara, Playwright) — CSS selectors and class name assertions that reference Optics classes or icon font classes will fail if those names change; search `spec/` for any affected class or token name +3. Determine whether each hit is still correct, needs updating, or is now dead code. +4. Note anything that can't be resolved automatically and flag it for visual QA. + +### A3. Bump the version and install + +Edit `package.json` to set `"@rolemodel/optics": ""`, then: + +```bash +yarn install +``` + +### A4. Check the new dist structure + +```bash +ls node_modules/@rolemodel/optics/dist/css/ +ls node_modules/@rolemodel/optics/dist/css/addons/fonts/ +``` + +Confirm that any import paths in the app's main stylesheet still exist in the new dist. Update any that have moved. + +### A5. Implement all required fixes + +Apply every fix identified in A2. + +### A6. Verify the CSS build + +Run the project's CSS build command (e.g. `yarn build:css`) and confirm it completes without errors. + +### A7. Pause for user review + +Present a summary of what was changed for this version and ask: + +> - Open a PR for this version? +> - Continue to the next version? +> - Stop here? + +If they want a PR, follow the PR step below, then ask about continuing. Return to A1 for the next version when they give the green light. + +--- + +## Mode B: All at once + +### B1. Fetch release notes for every version in range + +```bash +gh release list --repo RoleModel/optics --limit 30 +``` + +For each release between the current version (exclusive) and the target (inclusive): + +```bash +gh release view --repo RoleModel/optics +``` + +Read every release note carefully. Flag anything under headings like **Component Changes**, **Base Token Changes**, **Layout Changes**, **Distribution Changes**, or **Breaking**. Additive-only releases require no action. + +### B2. Audit the codebase against all flagged changes + +Apply the same general approach as Mode A step A2, covering all flagged changes across all versions. + +### B3. Bump the version and install + +Edit `package.json` to set `"@rolemodel/optics": ""`, then: + +```bash +yarn install +``` + +### B4. Check the new dist structure + +```bash +ls node_modules/@rolemodel/optics/dist/css/ +ls node_modules/@rolemodel/optics/dist/css/addons/fonts/ +``` + +Confirm that any import paths in the app's main stylesheet still exist in the new dist. Update any that have moved. + +### B5. Implement all required fixes + +Apply every fix identified in B2. + +### B6. Verify the CSS build + +Run the project's CSS build command (e.g. `yarn build:css`) and confirm it completes without errors. + +--- + +## PR step (optional) + +If the user wants a PR: + +```bash +git add +git commit -m "[TICKET] Upgrade Optics to vX.Y.Z" +git push -u origin +gh pr create --draft --title "[TICKET] Upgrade Optics to vX.Y.Z" \ + --reviewer \ + --body "..." +``` + +Check for a PR template (`cat .github/pull_request_template.md`) and follow it exactly. + +After creating the PR, mark it ready for review only if the user asks: + +```bash +gh pr ready +```