Development workflow

End-to-end recipe for going from "I have a bug to fix" to "PR submitted".

0. Confirm the issue qualifies

This repo is in maintenance mode (see AGENTS.md). Confirm the bug is a 5.9/6.0 regression / crash / security / lib.d.ts change before investing time. Most other work goes to microsoft/typescript-go.

1. Fork and clone

git clone --depth=1 https://github.com/<your-fork>/TypeScript
cd TypeScript
git remote add upstream https://github.com/microsoft/TypeScript
npm ci
npm install -g hereby   # or use npx hereby everywhere

2. Branch

git checkout -b fix/short-description

PRs are squash-merged, so the branch's commit history doesn't appear in main. Don't worry about polished history; focus on a clear PR title and description.

3. Reproduce the bug

Add a failing test under tests/cases/compiler/ (for type-checking issues) or tests/cases/fourslash/ (for language-service issues). The test should fail on main and pass with your fix. See how-to-contribute/testing for syntax.

hereby runtests --tests=myNewTestName

Inspect generated baselines under tests/baselines/local/ and confirm they demonstrate the bug.

4. Fix the bug

Make code changes. Most fixes touch one or two files in src/compiler/ or src/services/.

For finding the right place to start, see systems/index. Common entry points:

• Parser issues — src/compiler/parser.ts.
• Binder issues — src/compiler/binder.ts.
• Type errors — src/compiler/checker.ts (54k lines; use section comments to navigate).
• Emit/transform issues — src/compiler/transformers/<area>.ts.
• Language-service issues — src/services/<feature>.ts.

5. Verify

Run your test again:

hereby runtests --tests=myNewTestName

If baselines change, inspect them:

git diff tests/baselines

Look for collateral changes — unrelated baseline changes usually mean your fix has unintended impact. If they're correct, accept them:

hereby baseline-accept

6. Run the full test suite

hereby runtests-parallel

This is mandatory before submitting a PR. Plan for 10–15 minutes. Any new failures must be either:

• Fixed (your change broke something).
• Accepted as intentional baseline updates (with a note in the PR description).

7. Lint and format

hereby lint
hereby format

Lint must pass with zero issues. Format runs dprint over the source — no diff after formatting means you're done.

8. Commit and push

git add src/ tests/
git commit -m "fix(checker): brief description of the change"
git push origin fix/short-description

9. Open the PR

In the description:

• Link to the issue (Fixes #N).
• Quote which AGENTS.md criterion the change qualifies under.
• Disclose any AI assistance.
• Summarise the intentional baseline diffs.

10. Iterate

Reviewers will leave comments. Push additional commits to the branch — don't force-push (squash-merge handles cleanup). Respond to each comment.

Editor setup

• VS Code is the team's primary editor; .vscode/launch.template.json provides debug configurations.
• Use the workspace TypeScript version (typescript.tsdk set to built/local) to dogfood your changes inside the editor.
• The repo's .editorconfig and .dprint.jsonc files configure your editor automatically.

Common gotchas

• CRLF line endings. Source files use CRLF. Run git config core.autocrlf input and git config whitespace=cr-at-eol locally.
• Long Windows paths. git config --global core.longpaths true before cloning.
• hereby LKG — only run when you're explicitly bumping the bootstrap compiler. Don't include LKG changes in feature PRs.
• Generated files. src/compiler/diagnosticInformationMap.generated.ts is regenerated by hereby generate-diagnostics. Don't hand-edit.