Issue Reporting

Relevant source files

This document describes how to effectively report issues to the TypeScript repository on GitHub, including bugs, feature requests, library definition problems, and module resolution issues. Following these guidelines ensures issues are actionable and helps maintainers respond efficiently.

For information about contributing code changes, see Contributing Guide. For information about the pull request process, see Pull Request Process.

Overview of Issue Reporting Process

TypeScript uses GitHub Issues with structured templates to manage bug reports, feature requests, and other feedback. The repository enforces specific requirements for each issue type to ensure quality and actionability.

Sources: CONTRIBUTING.md31-77 .github/ISSUE_TEMPLATE/bug_report.yml1-10

Pre-Filing Requirements

Before creating any issue, all reporters must complete these mandatory steps:

1. Read the FAQ

The TypeScript FAQ contains answers to common questions and documents known limitations that are not bugs. Issues asking questions already answered in the FAQ are closed without elaboration.

Sources: CONTRIBUTING.md33-38

2. Search for Duplicates

Search existing issues thoroughly before filing new reports. The repository has thousands of open and closed issues covering most common scenarios.

Search Strategy:

Method	Example	Notes
GitHub Search	Search in repository issues	Basic but limited
Search Engine	`site:github.com/microsoft/TypeScript <keywords>`	Better relevancy ranking
Error Codes	Search for diagnostic codes like `TS2822`	Direct match for compiler errors
Function Names	Search top function names from stack traces	For crash reports

Search Tips:

Don't restrict to open issues only - closed issues may contain relevant duplicates.
Check for synonyms (e.g., "interface" issues often apply to "type aliases").
Read beyond the first page of results.
Search for the specific title of the issue you are about to log.

Sources: CONTRIBUTING.md39-49 .github/ISSUE_TEMPLATE/bug_report.yml7-12

3. Verify Issue Type

Questions about usage should be directed to:

The issue tracker is exclusively for bugs and suggestions, not usage questions.

Sources: CONTRIBUTING.md50-55 README.md44-46

Issue Templates and Requirements

TypeScript provides several structured issue templates, each with specific required fields to facilitate triage.

Sources: .github/ISSUE_TEMPLATE/bug_report.yml1-100 .github/ISSUE_TEMPLATE/feature_request.yml1-80

Template Details

For details on specific reporting categories, see the following child pages:

Bug Reports: Document how to file effective bug reports including search terms, version info, reproducible examples, and regression identification.
Feature Requests: Document how to propose new features including the viability checklist and TypeScript's design constraints.
Library Definition Issues: Document how to report issues with lib.d.ts files and the process for DOM API updates via TypeScript-DOM-lib-generator.
Module Resolution Issues: Document how to debug and report module resolution issues including --traceResolution and --showConfig output.

Automated Issue and PR Management

The TypeScript repository uses several GitHub Actions workflows to maintain issue quality and validate contributions.

Twoslash Repro Testing

The twoslash-repros.yaml workflow allows maintainers to run code samples from issues against specific TypeScript versions to confirm bugs or perform bisections. Sources: .github/workflows/twoslash-repros.yaml1-35

PR Modified Files Checks

The pr-modified-files.yml workflow (referenced in standard maintenance) validates pull requests that modify sensitive files:

Generated DOM Files: Modifications to files like src/lib/dom.generated.d.ts are automatically flagged, as these must be changed in the TypeScript-DOM-lib-generator repository.
API Surface: Changes to tests/baselines/reference/api/typescript.d.ts indicate a change to the public compiler API and require explicit review.

Sources: .github/workflows/ci.yml125-131 .github/workflows/new-release-branch.yaml78-87

General Quality Guidelines

Code Samples

Effective code samples are:

Isolated: Remove all unnecessary code and external dependencies.
Self-contained: The code should be runnable/checkable as-is.
Clear: The behavior you expect vs. the behavior you see should be obvious.

Sources: CONTRIBUTING.md56-64 .github/ISSUE_TEMPLATE/bug_report.yml69-79

Version Information

Always specify the version of TypeScript where the issue occurs. You can find this by running tsc --version. It is highly recommended to test against the nightly build (npm install typescript@next) before reporting.

Sources: CONTRIBUTING.md59-63 README.md23-27

Current Project Status and Scoping

🚨 Important: Development in this repository is winding down as the team moves toward a new implementation (TypeScript-go). PRs and issues for this codebase are currently limited to:

Critical 6.0 issues (regressions from 5.9).
Security issues.
Crashes that impact mainline usage.

Feature additions and general behavioral changes are currently on pause until the next major version is completed.

Sources: CONTRIBUTING.md5-6 README.md31-39

Automated Triage

The repository employs a bot system (typescript-automation[bot]) to handle routine tasks like setting versions, creating release branches, and updating the Last Known Good (LKG) compiler artifacts.

Sources: .github/workflows/new-release-branch.yaml89-91 .github/workflows/update-package-lock.yaml53-56