贡献指南

贡献简介

TypeScript 欢迎通过修复 bug 和添加新功能来贡献。在贡献之前，请熟悉 TypeScript 仓库架构并仔细阅读以下指南。

来源： CONTRIBUTING.md111-122 CONTRIBUTING.md48-146

设置开发环境

开始之前，请确保您具备以下先决条件

一个 GitHub 账户
Node.js (当前版本或 LTS 版本)
一个代码编辑器 (推荐 VS Code)

安装步骤

1. Fork the TypeScript repository on GitHub
2. Clone your fork locally: git clone https://github.com/YOUR-USERNAME/TypeScript.git --depth=1
3. Install the hereby tool: npm install -g hereby
4. Change to the TypeScript folder: cd TypeScript
5. Install dependencies: npm ci
6. Build and test: hereby runtests-parallel

--depth=1 标志通过创建仅包含最新提交的浅克隆来节省时间，而无需完整的提交历史。

使用开发容器

如果您更喜欢在容器中进行开发，该仓库包含一个开发容器配置，可与 VS Code 一起使用

将 TypeScript 仓库克隆到本地，然后使用“在容器中打开文件夹”命令，或者
使用“在容器卷中克隆仓库”命令

来源： CONTRIBUTING.md50-69 CONTRIBUTING.md94-100 .devcontainer/devcontainer.json1-44

常见开发任务

TypeScript 仓库使用 hereby 工具来执行常见的开发任务。以下是最常用的命令

命令	描述
`hereby local`	将编译器构建到 built/local
`hereby clean`	删除已构建的编译器
`hereby LKG`	用已构建的版本替换上一个已知良好版本
`hereby tests`	构建测试基础设施
`hereby runtests`	使用已构建的编译器运行测试
`hereby runtests-parallel`	并行运行测试 (推荐)
`hereby baseline-accept`	在测试更改后接受新的基线
`hereby lint`	在 TypeScript 源代码上运行 eslint

您可以运行 hereby --tasks 来查看所有可用的任务。

使用本地构建

使用 hereby 构建后，您可以通过运行以下命令来使用本地构建

node <repo-root>/built/local/tsc.js [options]

这使您可以在提交拉取请求之前测试您的更改。

来源： CONTRIBUTING.md71-89 CONTRIBUTING.md108-112

贡献流程

查找可处理的问题

TypeScript 团队使用以下标签标记已准备好供社区贡献的问题

“求助”标签 (https://github.com/microsoft/TypeScript/blob/6afd0fb7/, help wanted)
“积压”里程碑

虽然您无需在开始处理问题前明确声明，但专注于这些已预先批准的问题可以增加您的贡献被接受的可能性。

贡献类型

TypeScript 接受两种主要类型的贡献

Bug 修复：必须引用 TypeScript 团队已批准的现有问题
功能：必须在建议问题中获得 TypeScript 项目维护者的批准（标记为“求助”或在“积压”里程碑中）

具有语言设计影响或已被外部工具充分满足的功能通常不会被接受。

来源： CONTRIBUTING.md113-128 CONTRIBUTING.md48-51

测试您的更改

TypeScript 项目拥有全面的测试套件。在提交拉取请求之前，对您的更改进行测试至关重要。

运行测试

要运行所有测试

hereby runtests-parallel

要运行特定子集的测试

hereby runtests --tests=<regex>

示例

运行所有编译器测试： hereby runtests --tests=compiler
运行特定测试： hereby runtests --tests=2dArrays

调试测试

您可以使用 VS Code 或 Node 来调试测试

hereby runtests --tests=2dArrays -i

该仓库还包含一个 VS Code 启动配置模板（.vscode/launch.template.json），您可以将其重命名为 launch.json，以便直接从 VS Code 调试测试。

添加测试

添加新测试

在 tests\cases\compiler 或 tests\cases\conformance 的适当子文件夹中添加一个 .ts 文件
确保测试能证明您的 bug 修复有效或您的新功能运行正常
根据需要使用元数据标签，格式为 // @metaDataName: value

对于跨多个文件的功能测试，请使用 @filename 标签

来源： CONTRIBUTING.md176-238

处理基线

TypeScript 测试会生成“基线”来检测编译器输出的差异。当您进行更改并修改这些基线时，需要验证并接受这些更改。

基线类型

对于编译器测试，基线通常包括

.js 和 .d.ts 输出
编译器产生的错误（.errors.txt）
每个表达式的类型（.types）
每个标识符的符号（.symbols）
源映射输出（.js.map）

审查和接受基线更改

运行测试： hereby runtests-parallel
如果检测到基线更改，请进行审查
```
git diff --diff-filter=AM --no-index ./tests/baselines/reference ./tests/baselines/local
```
或者，设置 DIFF 环境变量并运行 hereby diff
在验证更改正确后，进行接受
```
hereby baseline-accept
```
将更新的基线文件包含在您的提交中

来源： CONTRIBUTING.md240-266

拉取请求指南

提交拉取请求时，请确保它满足以下要求

描述：包含对您的更改意图的清晰描述
分支：将您的 PR 基于 `main` 分支上的最新提交
测试：包含涵盖您更改的充分测试
代码风格：遵循代码指南
行尾符：在您的 git 配置中设置 autocrlf = input 和 whitespace = cr-at-eol

提交惯例

避免强制推送更改，尤其是在根据审查反馈更新 PR 时。强制推送的更改在 GitHub 上不易查看。由于 TypeScript PR 是通过 squash-merge 合并的，因此 PR 分支上的具体提交不如使更改易于审查那么重要。

法律要求

首次提交拉取请求时，您需要完成贡献者许可协议（CLA）。这证明您根据项目许可证条款授予使用您的贡献的权限，并且该工作受适当版权保护。

来源： CONTRIBUTING.md130-149

贡献库文件

TypeScript 的库声明文件有三个重要位置

src/lib：在进行更改时应编辑的源文件
lib：定期更新的“上一个已知良好”（LKG）版本
built/local：构建输出位置

标准库更改

对于 src/lib 中的标准库文件，大多数都可以手动更新，但生成的文件除外。

进行更改后，使用 hereby 构建项目，以更新 built/local/ 中的文件。

生成的 DOM 文件

文件 src/lib/dom.generated.d.ts 和 src/lib/webworker.generated.d.ts 是自动生成的。要修改这些文件，您需要贡献到 TypeScript-DOM-lib-generator 仓库。

来源： CONTRIBUTING.md150-170 src/lib/README.md1-27

定位

所有用户可见的字符串都存储在 diagnosticMessages.json 中。如果您对此文件进行了更改，请运行 hereby generate-diagnostics 来更新 diagnosticInformationMap.generated.ts 中的 Diagnostic 接口。

有关诊断消息的更多信息，请参阅编码指南。

来源： CONTRIBUTING.md268-273

仓库组织结构

TypeScript 仓库遵循特定的结构，旨在管理其复杂性。以下是关键目录的简化视图：

来源： .gitignore1-67

其他资源

TypeScript Compiler Notes: 编译器工作原理的文档
Coding Guidelines: 代码风格和约定指南
TypeScript 官网: 官方 TypeScript 网站
TypeScript 社区 Discord: TypeScript 用户和贡献者的社区聊天

来源： CONTRIBUTING.md173-174 README.md29-40