How to contribute

This section is the working contributor's manual for the withastro/astro monorepo. The canonical source of policy is CONTRIBUTING.md at the repo root; the pages below summarize and link into it.

Picking up work

• Browse the issue tracker filtered by good first issue or help wanted.
• For triage, the priority labels p1 (cosmetic) through p5 (release-blocker) are documented in the "Assign priority to bugs" section of CONTRIBUTING.md.
• The triage/ workspace (linked via pnpm-workspace.yaml) is the standard place to drop reproductions while debugging.
• Discord (#contributors): https://astro.build/chat

PR process

The expected lifecycle is:

1. Fork, branch off main, implement your change.
2. Add a changeset (pnpm exec changeset) for any change to a published package. Examples (examples/*) do not need a changeset.
3. Pass pnpm run lint, pnpm run format:ci, and pnpm run test for the affected packages.
4. Open a PR. The CI runs the full test matrix (.github/workflows/ci.yml).
5. A maintainer reviews. Reviews are voluntary and best-effort; pinging once after a few days is fine.
6. After approval and CI green, a maintainer merges. Releases are then cut by the bot via the [ci] release PR.

The pr preview label triggers a snapshot release for any package with a pending changeset. Comment !bench to run the benchmark suite against main.

Definition of done

A PR is done when:

• All CI jobs are green (build, lint, test, e2e where applicable).
• A changeset is present iff the change affects a published package.
• New behavior has tests (mocha or node:test, plus Playwright e2e for HMR/hydration).
• Breaking changes are flagged in the changeset as major.
• Touched files still pass pnpm run format:ci.

Sub-pages

• Development workflow — branch, build, dev loop, changesets, snapshots, prereleases.
• Testing — mocha, node:test, e2e, fixtures, the astro-scripts test runner.
• Debugging — Vite debug logs, dev overlay, common error classes, the optimize-deps symptoms.
• Patterns and conventions — the runtime/non-runtime split, internal exports, decoupling, error data.
• Tooling — astro-scripts, bgproc, agent-browser, Biome, knip, turbo, pnpm overrides.