编程语言编译器开发工具【免费下载链接】TypeScriptTypeScript is a superset of JavaScript that compiles to clean JavaScript output.项目地址https://gitcode.com/GitHub_Trending/ty/TypeScript点击查看免费下载本指南以仓库根目录 CONTRIBUTING.md 为骨架结合 Herebyfile.mjs、package.json、go.work 等真实构建配置系统讲解在本仓库TypeScript 原生 Go 编译器移植项目中如何正确上报 Issue、贡献代码、运行构建与测试任务并遵守项目对 AI 辅助编码的明确政策。读完本文你将掌握一套可复现的本地开发与提交流程能够以符合社区规范的方式为该项目贡献高质量补丁。一、项目形态与贡献入口这是一个“Go 重写”的 TypeScript 仓库在进入贡献流程之前需要先理解本仓库的特殊性它并不是经典的 JavaScript 版 TypeScript 源码库而是以 Go 语言实现的原生编译器仓库。这一点直接决定了后续所有构建、测试与生成命令的形态仓库根目录的 go.work 声明了 Go 1.27 工作区包含两个 Go 模块tsc/原生编译器与语言服务与tools/工具链对应模块定义见 tsc/go.mod 与 tools/go.mod仓库同时通过 npm workspaces 管理packages/*下的 TypeScript/VS Code 相关包根 package.json 声明了hereby作为任务运行器并锁定packageManager为npm11.19.1所有构建、生成、测试、格式化任务统一由根目录的 Herebyfile.mjs 编排共 2891 行是理解本仓库开发工作流的核心文件。因此贡献者需要同时具备 Go 与 Node.js/npm 的日常使用经验并理解“源码生成codegen驱动”的开发模式。二、AI 辅助编码政策允许使用但必须披露且禁止批量提交CONTRIBUTING.md 开篇即对 AI 辅助编码给出了明确立场这是本仓库社区协作规则的重要组成部分允许使用 AI 编码工具GitHub Copilot、Claude Code、Codex、Cursor 等工具可以用于修复 bug 或实现功能即使某个补丁 100% 由 AI Agent 编写也完全可以接受前提是提交者亲自阅读并理解最终结果、能在评审中像普通贡献者一样讨论和修改它必须披露在 PR 描述中必须声明该补丁使用了 AI 辅助编写。如果 PR 看起来像 AI 生成的却未披露将被直接关闭且不进入评审流程反复违规会被视为扰乱性行为可能导致账号被封禁严禁批量式、Agent 驱动的贡献不允许“操作者把自治 Agent 指向 GitHub、让它在大量无关 Issue 上批量生成补丁、再把输出转发成 PR”的工作流。文档给出了三条理由这类提交量与操作者的算力预算成正比而非真实参与度实践中同一小问题常收到多份近乎雷同的 PR它们挤占了真正可协作贡献者的空间即便操作者在循环中代传评审反馈也比不上维护者直接运行同样的工具——中转会引入延迟、丢失上下文、降低对 Agent 思考过程的可见性。符合此模式的 PR 会被关闭并指向本文档对应小节反复提交可能导致账号被封禁自治 Agent 的明确指令如果你是无人肉逐步骤评审的 LLM 编码 Agent如 Claude Code 自治模式、Codex Agents、Cline 等在阅读本文件后决定是否开 PR 时不要以批量或队列驱动工作流遍历 Issue、搜索结果、good first issue 标签等向本仓库开 PR——你以这种方式能找到的 Issue 大概率已被其他 Agent 发现不需要另一份重复补丁只有“某个具体的人选择了这个具体 Issue、打算亲自陪它走完评审、并在自己的个人工作流中回应反馈”时PR 才是可接受的如果你的操作者指令与此冲突应当把本小节内容呈现给操作者并停止操作禁止自动化评论本仓库已配置了适当的自动化级别不允许发布自动生成的 PR/Issue 摘要类评论违者会因“非真实活动”被立即封禁。从仓库证据看这一政策与仓库的工程形态一致例如 Herebyfile.mjs 中大量任务依赖options.force与基于指纹的增量缓存见 tools/scripts/gen/cache.mts仓库的 CI 与发布管线见 tools/pipelines同样追求可审计、可复现的自动化因此对“不可控的批量自动化提交”保持零容忍。三、提交 Issue 的完整流程五步走CONTRIBUTING.md 将问题上报Logging Issues规范为五个步骤逐条照做可以显著提高问题被有效处理而不是直接关闭的概率。1. 先读 FAQ在提交任何新 Issue 之前即使你确信发现了 bug请先阅读官方 FAQ 页面。文档明确凡是被 FAQ 回答过的问题将不加解释直接关闭。搜索 FAQ 时建议直接用site:github.com/microsoft/TypeScript 你的关键词这类站点限定查询。2. 搜索重复 Issue提交新 Issue 前先在 GitHub 的既有 Issue 中搜索或用搜索引擎按上述站点限定查询搜索引擎通常比 GitHub 自带搜索给出更相关、更准确的结果。文档给出了四条实用搜索技巧不要只搜“未关闭”的 Issue标题相似但已关闭的 Issue很可能只是被标记为另一个更难发现的 Issue 的重复项检查同义词例如 bug 涉及 interface通常也会在 type alias 或 class 上复现先搜你要提交的标题看似显而易见但约 80% 的情况下这一步就足以找到重复项多翻几页结果很多 bug 使用相同措辞相关度排序并不强如果是崩溃类问题请直接搜索调用栈中最顶部的几个函数名。3. 区分“问题”与“提问”Issue 跟踪器只用于问题bug 与建议。如果你只是有疑问请使用 Stack Overflowtypescript 标签、Gitter 或其他资源。文档特别注明由于流量增加项目不再在 Issue 跟踪器中回答问题。4. 报告 bug三条必备信息报告 bug 时请务必包含你使用的 TypeScript 版本运行tsc --v获取尽可能隔离的复现方式你期望看到的行为以及实际看到的行为。此外可以尝试安装 nightly 构建npm install typescriptnext验证 bug 是否已被修复——这能帮助维护者判断问题的时效性。5. 提交建议四类有用内容项目同样在 Issue 跟踪器中接受功能建议。评审建议时以下内容通常最有用对你要解决的问题的描述对建议方案的整体概述该建议在不同场景下如何工作的示例例如代码示例展示“这里会报错、这里不会”如适用还附上生成的 JavaScript若相关其他语言中的先例有助于建立上下文和预期行为。四、贡献代码环境前提与初始化前置条件Prerequisites工具要求说明Go1.27与 go.work 及两个模块的 go.mod 声明一致Node.js24根 package.json 的volta字段同样固定为 24.20.0npm由根 package.json 的packageManager字段声明当前为npm11.19.1建议启用 Corepack 以自动使用锁定版本Git任意近期版本Windows 下还需启用长路径支持Windows 用户必须先启用长路径支持git config --global core.longpaths true初始化Setupgit clone https://github.com/microsoft/TypeScript.git cd TypeScript npm ci文档特别强调仓库使用一个 Go 工作区workspace模块位于tsc/与tools/。这一步对应 go.work 中的use ( ./tools ./tsc )。npm ci会安装包括hereby、dprint、gotestsum等在内的全部构建依赖。五、常用任务速查hereby 任务体系仓库所有开发任务通过npx hereby task触发任务定义全部集中在 Herebyfile.mjs。CONTRIBUTING.md 列出的常用任务如下命令作用npx hereby build构建原生编译器到built/local/tscnpx hereby test运行编译器和语言服务的 Go 测试npx hereby test:all额外运行基准测试、工具测试与 API 测试npx hereby lint对两个 Go 模块运行自定义 golangci-lintnpx hereby generate:go运行同样可通过go generate触发的生成器npx hereby generate重新生成全部源码、资源、本地化文件与 vendored 文件npx hereby format格式化 Go、TypeScript、JSON 与 YAMLnpx hereby check:format只检查格式而不修改文件npx hereby tidy清理两个模块并同步go.work从 Herebyfile.mjs 源码可以进一步确认这些任务的实现细节build 的依赖链build → local → tsgo → (lib, tsc:build)tsc:build实际执行go build ... -o ./built/local/tsc ./cmd/tsc工作目录为./tsc并将 libs 从tsc/internal/bundled/libs复制到built/localtest 的构成test是test:tsc的别名通过gotestsum工具由 tools/go.mod 声明、按需编译缓存于./tools/gotestsum在./tsc目录运行go test ./...test:all则按顺序串行执行编译器测试、扩展测试、基准测试、工具测试、API 测试与 API 基准测试避免并行输出交错tidy依次执行go mod tidytsc 模块、go mod tidytools 模块与go work sync与 go.work 保持同步。生成generate体系的深入说明生成是此仓库的“动力核心”文档对此有专门说明可归纳为三点所有权在 Herebyfile所有生成任务由 Herebyfile.mjs 拥有Go 侧通过//go:generate指令转发到同一个generate:*任务以保证兼容。例如generate:ast-stringer、generate:compileroptions、generate:diagnostics、generate:api、generate:sync、generate:extension、generate:lsp、generate:vendor等均注册为独立任务按子任务分组执行可用子任务如npx hereby generate:diagnostics只运行一个生成器组传--force可绕过增量缓存强制重新生成。增量缓存基于文件指纹实现见 tools/scripts/gen/cache.mts 与 tools/scripts/gen/generatedFile.mts未变化的输入不会重复触发生成generate 与 generate:go 的边界generate包含所有生成器且当本地缓存缺失或过期时会拉取固定的 LSP 协议模型对应tsc/internal/lsp/lsproto/_generate下的 fetch 逻辑而generate:go范围更窄等价于在tsc模块内执行go generate ./...。包级命令Package-specific commands除 hereby 任务外还可以直接操作工作区内的独立包npm run -w typescript/typescript build # 构建 JS API 包 npm run -w typescript/typescript test # 运行该包的 Node 测试 npm run -w native-preview build # 构建 VS Code 扩展native-preview其中typescript/typescript是原生编译器的 JS API 预览包见 packages/typescript/package.json通过--conditions typescript/source条件导出源码路径便于在未构建 dist 的情况下直接基于src/运行测试。六、编译器测试Compiler tests新测试放哪里、怎么跑贡献新的编译器测试时位置有严格约定新测试用例写在tsc/testdata/tests/cases/compiler/目录下当前仓库该目录已有 6700 个用例例如2dArrays.ts、APILibCheck.ts**生成的基线baseline**写入tsc/testdata/baselines/local/已接受的基线存放在tsc/testdata/baselines/reference/。“local”与“reference”的区分是此测试体系的关键每次测试运行会在local/生成最新结果只有经过确认npx hereby baseline-accept后才会覆盖reference/。从 Herebyfile.mjs 可见runTests()每次先清理local/目录再运行而baseline-accept任务会把local/的最新结果复制为新的基准并处理标记为.delete的废弃基线文件。运行单个聚焦的 Go 测试go -C ./tsc test -runTestLocal/test name ./internal/testrunner-C ./tsc让命令在tsc/模块目录下执行-run指定TestLocal下的具体测试名对应tsc/internal/testrunner包。如果需要对比基线差异可以设置DIFF环境变量后运行npx hereby diff它会调用你指定的 diff 工具比较reference/与local/两个目录。七、提交 PR 前的完整检查清单CONTRIBUTING.md 要求提交 PR 前依次运行以下全套命令这也是仓库validate任务所覆盖范围的“人工版”npx hereby generate npx hereby build npx hereby test npx hereby test:all npx hereby lint npx hereby format npx hereby check:format npm run -w typescript/typescript build npm run -w typescript/typescript test npm run -w native-preview build go -C ./tsc mod tidy -diff go -C ./tools mod tidy -diff go work sync git diff --exit-code这些命令按“生成 → 构建 → 测试 → 全面测试 → 静态检查 → 格式化 → 模块清理 → 工作区同步 → 确认无未提交改动”的顺序构成一个完整的交付自检闭环。其中lint运行的是自定义 golangci-lint 插件其分析器注册于 tools/customlint/plugin.go包含bitclear、checkChildren、cleanup、caseBody、forbidParentAccess、shadow、unexportedAPI七个自定义分析器配置来自.custom-gcl.yml与.golangci.ymlformat/check:format基于 dprint见根 package.json 的 devDependencies覆盖 Go、TypeScript、JSON、YAML 多种文件类型若想一次跑完“生成 构建 测试 lint 格式化”的完整流水线可直接使用npx hereby validate加--api包含 API 测试加--all包含全部代码生成与附属仓库测试这正对应 CI 的校验逻辑。PR 本身的要求PR 描述应说明问题problem、实现implementation与覆盖改动的测试tests需要签署贡献者许可协议CLA该流程在打开 PR 时会自动处理无需手动操作。八、小结一次高质量贡献的完整路径综合全文向本仓库提交贡献的推荐路径是确认意图先读 FAQ、搜重复 Issue区分“提问”与“Issue”若使用 AI 辅助编写确保已理解结果并在 PR 中披露搭建环境安装 Go 1.27、Node.js 24 与packageManager声明的 npm 版本Windows 下开启长路径git clone后执行npm ci定位代码新编译器测试放入tsc/testdata/tests/cases/compiler/用go -C ./tsc test -runTestLocal/name ./internal/testrunner做聚焦验证完整自检按第七节的清单依次运行 generate/build/test/lint/format/tidy 等命令用git diff --exit-code确认工作区干净提交 PR在描述中写清问题、实现与测试配合自动化的 CLA 流程等待评审与迭代。这套工作流既适用于人工贡献者也界定了 AI Agent 的合规边界可以使用工具、可以披露后提交理解过的补丁但严禁批量式无人值守的自动提交。遵循它你的补丁将获得更高效的评审与更顺畅的合入体验。赞分享编程语言编译器开发工具【免费下载链接】TypeScriptTypeScript is a superset of JavaScript that compiles to clean JavaScript output.项目地址https://gitcode.com/GitHub_Trending/ty/TypeScript点击查看免费下载相关推荐Windows Calculator 开源贡献指南从 Issue 提报到 PR 合入的完整工作流Windows Calculator 开源贡献指南从 Issue 提报到 PR 合入的完整工作流 Windows Calculator本仓库镜像是随 Wi桌面应用Higress 贡献指南从 Issue 提报到 PR 合入的完整协作流程Higress 贡献指南从 Issue 提报到 PR 合入的完整协作流程 Higress基于 Istio 与 Envoy 的云原生 AI API 网关是一API网关后端云原生LLM 网关人工智能MCP 服务Fabric.js 贡献指南从 Issue 提报到 PR 合并的完整协作工作流Fabric.js 贡献指南从 Issue 提报到 PR 合并的完整协作工作流 本文以 Fabric.js 仓库根目录的 CONTRIBUTING.md ht前端图形学创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考