CONTRIBUTING_zh.md
欢迎来到 Nacos！本文档是关于如何为 Nacos 做贡献的指南。
Nacos 采用宽松的 Apache 2.0 许可证发布，遵循标准的 Github 开发流程，使用 Github Issue 跟踪问题并将 Pull Request 合并到 develop 分支。如果您想要贡献，无论是简单的修复还是重大的新功能，请不要犹豫，但请遵循以下指南。
我们始终非常欢迎各种贡献，无论是简单的代码清理还是重大的新功能。我们希望每种编程语言都有高质量、文档完善的代码。代码并不是贡献项目的唯一方式，我们同样重视文档和与其他项目的集成，并乐于接受这些方面的改进。
请务必阅读并遵守我们的行为准则。
在贡献之前，请阅读并正确配置 Nacos 代码规范：
style/NacosCheckStyle.xmlstyle/nacos-code-style-for-idea.xmlstyle/codeStyle.md邮件列表是讨论 Nacos 相关任何事项的推荐方式：
如果您在 Nacos 项目中发现 bug 或文档错误，请通过创建 Issue 告知我们。我们非常重视 bug 和错误，认为任何问题都不算小问题。在创建 bug 报告之前，请先检查是否已存在报告相同问题的 Issue。
为了使 bug 报告准确且易于理解，请尽量创建符合以下要求的 bug 报告：
具体：尽可能包含详细信息：哪个版本、什么环境、什么配置等。如果 bug 与运行 Nacos 服务器相关，请附上 Nacos 日志（启动日志和 Nacos 配置信息尤为重要）。
可复现：包含重现问题的步骤。我们理解某些问题可能难以复现，请包含可能导致问题的步骤。如有可能，请将受影响的 Nacos 数据目录和堆栈跟踪附加到 bug 报告中。
唯一：不要重复已有的 bug 报告。
在创建 bug 报告之前，阅读 Elika Etemad 关于如何提交好的 bug 报告的文章可能会有所帮助。
请勿通过 GitHub Issues 报告安全漏洞。请通过 ASRC（阿里巴巴安全响应中心）进行报告。
Nacos 欢迎任何角色的新参与者，包括用户、贡献者、Committer 和 PMC。
我们鼓励新人积极参与 Nacos 项目，从用户角色发展到贡献者、Committer，甚至 PMC。
如果您发现文档中的拼写错误、代码中的 bug，或者想要新功能、提出建议，可以在 GitHub 上创建 Issue 进行反馈。
如果您想直接参与贡献，可以选择以下标签的 Issue：
请注意，每个 PR 必须关联一个有效的 Issue，否则 PR 将被拒绝。
为避免重复工作并提高协作效率，请在认领 Issue 时遵循以下流程：
/assign 即可自动认领/unassign 即可/unassign 即可取消认领在提交更改之前，请确保：
阅读并遵循 Nacos 代码规范，确保您的 IDE 已配置代码风格并安装了必要的插件。
如果更改是非琐碎的，请包含覆盖新功能的单元测试。
如果您正在引入全新的功能或 API，最好先发起讨论并在基本设计上达成共识。
此贡献流程适用于所有 Nacos 社区内容，包括但不限于 Nacos、Nacos wiki/doc、Nacos SDK。
将 alibaba/nacos 仓库 Fork 到您的 Github 账号。
git clone ${您的_fork_nacos_仓库地址}
cd nacos
git remote add upstream https://github.com/alibaba/nacos.git
git remote -v
# origin ${您的_fork_nacos_仓库地址} (fetch)
# origin ${您的_fork_nacos_仓库地址} (push)
# upstream https://github.com/alibaba/nacos.git (fetch)
# upstream https://github.com/alibaba/nacos.git (push)
git fetch origin
git fetch upstream
我们使用 develop 分支作为开发分支，这是一个不稳定的分支。基于 upstream/develop 创建新分支：
# 从远程仓库检出分支到本地
git checkout -b upstream-develop upstream/develop
# 创建开发分支（通常使用 issue 编号作为分支名）
git checkout -b develop-issue#${issue编号}
进行修改时，请确保：
Fix xxx problem/bugFor xxx 描述，例如：For codestyleFor #10000, Fix xxx problem/bug在推送代码之前，请在本地运行以下命令以尽早发现问题：
mvn -B clean compile apache-rat:check checkstyle:check spotbugs:check -DskipTests
| 检查项 | 说明 |
|---|---|
compile | 代码是否能正常编译 |
apache-rat:check | 所有源文件是否包含 Apache License 头 |
checkstyle:check | 代码风格是否符合阿里巴巴 Java 开发规约 |
spotbugs:check | 是否存在 SpotBugs 检测到的高优先级 bug |
运行单元测试：
mvn clean test
在您进行修改的同时，其他人的更改可能已经被提交和合并。此时可能会有冲突，请使用 rebase 命令进行合并和解决：
git fetch upstream
git rebase -i upstream/develop
或者
git checkout upstream-develop
git pull
git checkout develop-issue#${issue编号}
git rebase -i upstream-develop
变基的好处：
Merge xxxx branch 的信息如果您使用 IntelliJ IDEA，建议使用 IDE 的版本控制面板，它有更方便的可视化界面来解决冲突和执行压缩操作。
git push origin develop-issue#${issue编号}
注意：如果在变基后再次推送时提示有冲突，可以强制推送到您的 fork 分支：git push -f origin develop-issue#${issue编号}。这是因为变基后提交 ID 发生了变化。
向 develop 分支创建 Pull Request，并遵循 PR 模板。
[ISSUE #123] Fix UnknownException when host config not exist。PR 中的每个提交都应有有意义的主题和正文。mvn -B clean apache-rat:check checkstyle:check spotbugs:check -DskipTests 确保基本检查通过。mvn clean install -DskipITs 确保单元测试通过。mvn clean test-compile failsafe:integration-test 确保集成测试通过。Nacos 社区将审核您的 Pull Request 并可能提出意见。您可以返回步骤 5 根据意见修改代码，并使用步骤 7 重新提交。
如果没有更多问题，Nacos 社区将合并您的 PR。恭喜您成为 Nacos 的正式贡献者！
每个新的源文件（.java、.xml 等）必须包含 Apache License 2.0 头。CI 会通过 apache-rat:check 自动检查，缺少 License 头的 PR 将无法通过。
请将以下头信息复制到每个新文件中（非 Java 文件请调整注释风格）：
/*
* Copyright 1999-2025 Alibaba Group Holding Ltd.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
在贡献文档时，请确认并检查以下内容：
Committer 会轮流审查代码，确保所有 PR 在合并前至少经过一名 Committer 的及时审核。如果我们有所疏漏，欢迎随时提醒。同时，我们也欢迎志愿者参与代码审查。
我们始终欢迎新的贡献者加入。我们看重的是持续的贡献、良好的品味和对项目的持续兴趣。如果您有兴趣成为 Committer，请联系现有的 Committer，他们可以帮助您完成这个过程。
一般来说，需要贡献 8 个非琐碎的补丁，并获得至少三个不同的人来审核（您需要三个人的支持）。然后请人提名您。您需要展示：
Committer 通过在带有 "nomination" 标签的 Nacos Issue 中通知团队来提名您，需要包含：
需要另外两名 Committer 附议您的提名。如果 5 个工作日（中国时间）内没有人反对，您就是 Committer 了。如果有人反对或需要更多信息，Committer 们会进行讨论并通常在 5 个工作日内达成共识。如果问题无法解决，将在现有 Committer 中进行投票。
在最坏的情况下，这个过程可能会持续两周。请继续贡献！即使在提名失败的罕见情况下，反对意见通常也是容易解决的，比如"需要更多补丁"或"没有足够的人熟悉此人的工作"。