chore: add .github/copilot-instructions.md for Copilot cloud agent onboarding#8543
chore: add .github/copilot-instructions.md for Copilot cloud agent onboarding#8543
Conversation
…boarding Agent-Logs-Url: https://github.com/QwikDev/qwik/sessions/ab321122-f094-4e24-883b-f1a4bb7e276f Co-authored-by: wmertens <54934+wmertens@users.noreply.github.com>
|
There was a problem hiding this comment.
Pull request overview
Adds a new .github/copilot-instructions.md document to onboard Copilot cloud agents with Qwik monorepo context, setup commands, architecture basics, and contribution workflow so agents can operate effectively in first session.
Changes:
- Introduces a Copilot cloud agent instructions file covering repo concepts (resumability/QRLs/signals/optimizer) and monorepo layout.
- Documents common dev commands (build/test/lint/api update/changesets) and key workflow/anti-pattern guidance.
- Captures known issues/workarounds to reduce iteration friction (API diffs, CI merge behavior, tooling enforcement).
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Package | Path | Description | | ||
| | --------------------------- | ------------------------------- | ---------------------------------------- | | ||
| | `@builder.io/qwik` | `packages/qwik` | Core framework (runtime + optimizer) | | ||
| | `@builder.io/qwik-city` | `packages/qwik-city` | Meta-framework (routing, loaders, adapters) | | ||
| | `@builder.io/qwik-react` | `packages/qwik-react` | React integration layer | |
There was a problem hiding this comment.
Markdown tables are written with a double leading pipe (|| ...), which renders as an extra empty first column in most renderers. Use a single leading | for the header/separator/rows (and apply consistently to the rest of the table) so the package table renders correctly.
| | Task | Command | Notes | | ||
| |------|---------|-------| | ||
| | Install deps | `pnpm install` | | | ||
| | Build (no Rust) | `pnpm build.local` | Full build for a fresh start | | ||
| | Build (with Rust) | `pnpm build.full` | Only needed after Rust changes | |
There was a problem hiding this comment.
This commands table also uses a double leading pipe (|| ...), which creates an unintended empty first column when rendered. Switch to a single leading | for the header/separator/rows to ensure the table displays correctly.
| | Rule | Setting | | ||
| |------|---------| | ||
| | Semicolons | `true` | | ||
| | Quotes | Single | | ||
| | Print width | 100 | | ||
| | Indentation | 2 spaces | |
There was a problem hiding this comment.
The code style table is using || at the start of each row, which will render an empty first column. Use a single leading | so the table formatting is correct.
| | Pattern | Usage | Example | | ||
| |---------|-------|---------| | ||
| | `use*` | Hooks (called in component or task scope) | `useSignal`, `useStore`, `useTask$` | | ||
| | `*$` | QRL boundary — optimizer extracts the closure | `component$`, `routeLoader$` | | ||
| | `create*` | Factory functions | `createDOM`, `createContextId` | | ||
| | `*.unit.ts(x)` | Unit test files | `qrl.unit.ts` | |
There was a problem hiding this comment.
The naming conventions table also starts rows with ||, which renders an extra blank column. Update it to standard markdown table syntax (single leading |) so it displays as intended.
| | Install deps | `pnpm install` | | | ||
| | Build (no Rust) | `pnpm build.local` | Full build for a fresh start | | ||
| | Build (with Rust) | `pnpm build.full` | Only needed after Rust changes | | ||
| | Build core only | `pnpm build.core` | Fast — Qwik + Qwik City + types | |
There was a problem hiding this comment.
The “Build core only” description doesn’t match what pnpm build.core actually runs. In package.json, build.core includes --api and --platform-binding in addition to --tsc --build --qwikcity, so it’s not just “Qwik + Qwik City + types” and may not be the fastest option. Please update the description (or adjust the recommended command) to match the script behavior.
| | Build core only | `pnpm build.core` | Fast — Qwik + Qwik City + types | | |
| | Build core packages | `pnpm build.core` | Builds Qwik + Qwik City + types, API docs, and platform bindings | |
| | Build (no Rust) | `pnpm build.local` | Full build for a fresh start | | ||
| | Build (with Rust) | `pnpm build.full` | Only needed after Rust changes | | ||
| | Build core only | `pnpm build.core` | Fast — Qwik + Qwik City + types | | ||
| | Build specific packages | `pnpm build --qwik --qwikcity --dev` | Skips type-check & generating | |
There was a problem hiding this comment.
The table recommends pnpm build --qwik --qwikcity --dev, but the flags reference below describes the core build flag as --build (which is the user-facing alias for the internal --qwik flag). For consistency and clarity, prefer documenting --build here as well, so readers don’t have to learn both names for the same flag.
| | Build specific packages | `pnpm build --qwik --qwikcity --dev` | Skips type-check & generating | | |
| | Build specific packages | `pnpm build --build --qwikcity --dev` | Skips type-check & generating | |
| ## Prerequisites and Setup | ||
|
|
||
| **Required versions:** Node ≥ 22.18.0, pnpm ≥ 10.14.0 | ||
|
|
There was a problem hiding this comment.
The prerequisites say “Required versions: Node ≥ 22.18.0”, but later the doc states .node-version pins Node 24 and suggests matching the exact version. Consider clarifying in this section that Node 24 (per .node-version/.nvmrc) is the recommended/CI version, while >=22.18.0 is the minimum supported by package.json engines.
| `Node >= 22.18.0` is the minimum supported version from `package.json` engines. For local development and CI parity, prefer the Node 24 version pinned in `.node-version` / `.nvmrc`. |
commit: |
Adds
.github/copilot-instructions.mdto give Copilot cloud agents the context needed to work efficiently in this monorepo from the first session.Contents
$-suffix transform, signals, Rust optimizerpnpm buildflag breakdownuse*/*$/create*conventions, test file patternsapi.update, editing generated files,console.log, etc.)api.updatediffs afterbuild.local, CI's auto-merge-with-main behavior, pnpm enforcement, Node version pinning