企业官网建设流程全解析

如何向 Kotlin 编译器仓库提交贡献：从挑选 issue 到提交 Pull Request？

【免费下载链接】kotlinThe Kotlin Programming Language.项目地址: https://gitcode.com/GitHub_Trending/ko/kotlin

这篇文章面向想在 Kotlin 编译器仓库（JetBrains/kotlin）里完成第一次贡献的开发者，目标是一条完整可执行的路径：在 YouTrack 上挑一个合适的 issue，在本地把仓库构建起来并跑通相关测试，按仓库规则整理提交信息，最后带着检查清单提交 Pull Request。仓库文档 docs/contributing.md 和 ReadMe.md 是这条路径的事实依据，下文所有命令和规则均出自这两个文件及各模块 README。

第一步：挑选一个适合入门的 issue

docs/contributing.md 给出了三条被官方推荐的入门路径：

1. 从 "Up For Grabs" 标签找 issue：Kotlin 的 issue 都登记在 YouTrack 的KT项目下。文档建议用带tag: {Up For Grabs} and State: Open条件的查询来列出所有标记为 "up-for-grabs" 的开放 issue。
2. 补写标准库文档：文档称之为 "a nice gentle way to contribute"——浏览标准库 API 文档，找到文档写得不够好的类或函数，提交一个补充文档的 patch。文档特别指出，理想情况下每个函数都应附带一个使用示例，示例通过@sample宏从测试函数中取代码，既能改善文档又能增加代码覆盖率。标准库中还有部分代码是从模板生成的，模板的运行方式见 libraries/stdlib/ReadMe.md。
3. 参与 Kotlin/Native：kotlin-native/README.md 有独立的贡献说明，并指向本仓库通用的贡献指南 docs/contributing.md。

两个协作约定要注意：

• 目前只有 committer 能把 issue 指派给自己，所以决定动手某个 issue 时，在 issue 下留一条评论说明你在做它即可。
• 文档建议先加入 Kotlin Slack 的#kontributors频道同步一下计划；如果是要贡献新的语言特性，则必须先走 KEEP（Kotlin Evolution Enhancement Proposal）流程并获得语言设计者认可，再开始实现。

准备本地构建环境

按 ReadMe.md 的 "Build environment requirements" 一节配置：

• 仓库使用 [Gradle toolchains] 特性，从 Eclipse Adoptium 自动选择和 provision 所需的 JDK，通常不需要手动准备 JDK。
• 如果只想用环境变量提供 JDK：支持的变量名列在 gradle.properties（如JDK_8、JDK_11、JDK_17、JDK_21等）；并且要让 Gradle 忽略自动探测的环境 JDK，需传入-Porg.gradle.java.installations.auto-detect=false（或把它写进$GRADLE_USER_HOME/gradle.properties）。
• Windows 上可能需要为仓库开启长路径支持：

git config core.longpaths true

本地构建与验证：跑哪些 Gradle 任务

克隆仓库后，用仓库自带的 Gradle Wrapper 构建和测试，Unix/macOS 用./gradlew，Windows 用gradlew：

./gradlew <tasks-and-options>

ReadMe.md 列出了与贡献验证直接相关的任务：

第一次配置时 Gradle 会下载intellij-core和idea-full（IntelliJ IDEA Community 完整包，供插件模块使用）等体积较大的依赖，网络不佳可能超时。文档给出的做法是在首次运行时追加超时参数：

./gradlew -Dhttp.socketTimeout=60000 -Dhttp.connectionTimeout=60000

验证成功与否就看这些任务是否通过：改动标准库跑coreLibsTest，改动编译器跑compilerTest。提交 PR 前的检查清单明确要求"本地跑过构建并验证了新功能、本地跑过相关测试且通过"（见文末清单）。

如果你的改动涉及 Kotlin/Native，按 kotlin-native/README.md 的 "Building from source"：

• 在仓库根目录创建local.properties文件，内容为一行kotlin.native.enabled=true；
• 平台前置条件：macOS 需要 Xcode（该文档"使用已发布版本"一节写 Xcode 15.4 or newer，"从源码构建"一节写 Xcode 26.4 or newer，两处表述不一致，以实际版本要求为准）；Linux 需要 glibc 2.23 或更新；Windows 需要 VS2019 C++ 构建工具和 Windows SDK 10.0.18362.0 或更新；
• 编译基础编译器分发包：

./gradlew :kotlin-native:dist

该命令会为主机目标构建编译器和 stdlib，但不包含 platform libraries；需要时追加:kotlin-native:distPlatformLibs任务。

另一个可能踩到的坑是依赖校验：仓库对全部 Gradle 构建启用了 dependency verification，Gradle 会核对所用依赖的 md5/sha256 哈希，本地构件缺失或哈希与 gradle/verification-metadata.xml 不一致时构建会以Dependency verification failed失败。ReadMe.md 说明该文件原则上只应随修改构建的提交一起更新；如果确实需要更新，可以运行./scripts/update-verification-metadata.sh脚本完成删除旧components段落并重新生成元数据两步。另注意：若项目目录下存在local.properties且其中写了kotlin.native.enabled=false，它的优先级高于命令行上的-Pkotlin.native.enabled=true，会导致 native 相关依赖没被写进校验元数据。

按仓库规则整理提交信息

docs/contributing.md 的 "Rules for commit messages" 一节规定了提交信息的规则，PR 里每一个 commit 都要满足：

内容规则

1. 正文解释 what 和 why，而不是 how；对每个非平凡改动都要额外说明为什么需要改。
2. 重要提交必须在信息中提及对应的 YouTrack issue。
3. 改动要与对应测试一起提交（除非合并后 commit 难以理解）。
4. 尽量避免 "Fixes after review" 这类提交，尽可能把它与有意义的提交 squash 到一起。
5. 首行（subject）保持干净、可读，给外部工具附加的信息全部放进正文。
6. 如果在正文中提及^[KTIJ-235 Fixed]这种形式，VCS 集成会向 YouTrack issue 添加 "Fix in Builds" 字段并自动标记为 fixed。

格式规则

1. subject 与正文之间空一行；
2. subject 首字母大写；
3. subject 结尾不加句号；
4. subject 使用祈使句；
5. 每行不超过 72 字符（IntelliJ 可在Settings → Version Control → Commit开启 "Commit Message Inspections"；vim 用户可用autocmd FileType gitcommit setlocal textwidth=72）。

仓库还有更细粒度的 docs/code_authoring_and_core_review.md，其中有几条直接影响 PR 能否顺利通过审查：

• 非功能性改动（重构、重排格式、代码重组）应拆成独立 commit，以便单独审查或排除出本次审查；
• 功能改动至少一个 commit 明确提及对应 YT ticket；一个 MR 涉及多个 ticket 时，建议按 ticket 拆成多个 MR；
• 改动必须有自动化测试覆盖，文档给出的判断标准是：把你的改动回退（保留测试），测试应当失败；修复回归时应有反映该回归的测试，且最好先写一个会失败的测试再动手修。

TODO 的处理约定

如果往master推送的代码里留下TODO注释或TODO("some reason")，docs/code_authoring_and_core_review.md 要求：

1. 创建 YouTrack ticket，说明该 TODO 要做什么、为什么做；
2. 给 ticket 加kotlin-todo标签；
3. 在TODO的标题行提及该 ticket，例如TODO KT-XXXX description。

评审者在看到新引入的TODO时会检查是否提及 ticket；ticket 被解决时要确保代码中对应的 TODO 都已处理。

提交 Pull Request 与提交前检查清单

docs/contributing.md 给出的提交方式是：fork 仓库后，向master分支发 Pull Request。创建自己的 fork 前，建议开启 rebase 拉取：

git config --global pull.rebase true

文档说明这样做可以避免本地仓库积累过多 merge commit，让 PR 保持简洁、易于合入。

提交 PR 前，文档要求你对以下每一点都能回答 "YES"：

• 提供了相关 YouTrack issue 的链接；
• 改动量合理，且只与所提供的 issue 相关；
• 能解释 PR 中每一处改动；
• 本地运行过构建并验证了新功能；
• 本地运行过相关测试且通过；
• PR 中没有 merge commit。

满足以上清单后，PR 即达到仓库文档定义的"可提交"状态；后续评审遵循 docs/code_authoring_and_core_review.md 中描述的机制——每个变更有一个对整体负责的 primary reviewer，CODEOWNERS对应的子系统评审人只负责各自子系统部分的一致性。

【免费下载链接】kotlinThe Kotlin Programming Language.项目地址: https://gitcode.com/GitHub_Trending/ko/kotlin