How to contribute

This section is the contributor's manual for the Deno repo. The user-facing manual lives at https://docs.deno.com; this is for people who want to change the runtime itself.

The official high-level rules are in .github/CONTRIBUTING.md. This section restates them in operational form and adds detail about the developer tooling, test layout, and patterns the codebase expects you to follow.

Where to start

If you want to…	Read this
Build, run, or iterate on Deno	Getting started
Understand the day-to-day branch → PR cycle	Development workflow
Add or run tests	Testing
Track down a bug	Debugging
Match the code style	Patterns and conventions
Use or modify the dev tooling	Tooling

The shortest possible loop

git checkout -b feature/my-change
# … edit code …
./x verify         # fmt + lint-js (pre-commit gate)
./x lint           # full lint, run if you touched Rust
cargo build --bin deno
./target/debug/deno run my-test.ts
cargo test specs   # or specific test suite
git commit -m "feat(area): describe the change"
git push origin feature/my-change
# Open PR against denoland/deno main

./x is the in-repo developer CLI (tools/x.ts). The same commands work as plain cargo / tools/format.js / tools/lint.js invocations if you prefer.

Definition of done

Before requesting review the project expects:

1. ./x fmt passes without changing files.
2. ./x lint (or ./x lint-js if only JS/TS changed) passes.
3. Relevant tests pass: ./x test, ./x spec, ./x node-test, etc.
4. New behavior is covered by tests, with spec tests preferred for user-visible behavior (tests/specs/).
5. The PR description includes the rationale and any relevant issue links.
6. AI-assisted contributions must be disclosed in the PR description. Failure to disclose can cause the PR to be rejected; using AI is fine, hiding it isn't (.github/CONTRIBUTING.md).

PR mechanics

• Branch off main. Push the feature branch and open a PR against denoland/deno main.
• Do not force-push. Add commits as you respond to review; everything is squashed at merge time. Keeping the incremental history makes review easier.
• Keep changes minimal and focused. Drive-by refactors belong in their own PR.
• Conventional commit prefixes are used in titles: feat(...), fix(...), perf(...), chore(...), test(...), etc., often with a scope like (ext/node), (cli), (lsp).

CI

CI is a set of GitHub Actions workflows under .github/workflows/. Notably, the .yml files are generated from sibling .ts scripts (ci.ts, pr.ts, etc.) — edit the TypeScript and re-run the generator if you need to change CI logic. Don't hand-edit *.generated.yml.

Key workflows:

• pr.generated.yml — runs on every PR (fmt, lint, build, test matrix)
• ci.generated.yml — runs on main and tags
• cargo_publish.generated.yml / npm_publish.generated.yml — release-time workflows
• node_compat_test.generated.yml — Node compat test runner
• ecosystem_compat_test.generated.yml — runs against external repos to catch regressions

Reading the rest of this wiki

If you're modifying a specific subsystem, the relevant deep-dive page is your fastest route:

• CLI flag parsing or a new subcommand → Systems → CLI
• A new op or extension → Extensions
• Module resolution / npm / JSR → Features → npm support, Features → JSR support
• LSP → Systems → LSP
• Permission model → Systems → Permissions