|
| 1 | +# 贡献帮助指南 |
| 2 | + 👋 Hi，我们很高兴见到您对[PowerNukkitX](https://github.com/PowerNukkitX/PowerNukkitX)项目所表现出的热情，我们的目标是为所有参与开发的参与者们提供一个良好的协作环境，因此我们决定列出一些在此过程中需要您牢记的事情，以下指南是根据过往经验总结而成的。 |
| 3 | + |
| 4 | + 但您需注意，这些规则本身不是"**官方规则**"，但您若遵循它们将帮助参与者们提高处理效率。 |
| 5 | + |
| 6 | +## 目录 |
| 7 | + |
| 8 | +1. <a href="#Catalogs-Faq#1">🧾 我想提交一个问题!</a> |
| 9 | +2. <a href="#Catalogs-Faq#2">💡 我想提交拉取申请!</a> |
| 10 | +3. <a href="#Catalogs-Swlang">🌐 切换语言 / Switch Languages</a> |
| 11 | + |
| 12 | +## <a id="Catalogs-Faq#1"></a>🧾 我想提交一个问题! |
| 13 | + |
| 14 | + 我们随时欢迎您提出任何问题，错误报告和功能建议，但请记住，如果该问题在可预期的时间点内被认定为不重要，无法解决等，我们也会将其忽略，因此Issues页面可能会出现长时间未解决或彻底关闭的问题反馈将会是正常情况。 |
| 15 | + |
| 16 | +* **在提交问题报告前，请您先搜索现有问题列表。** |
| 17 | + |
| 18 | + 出于管理目的，我们会关闭与先前就存在的问题反馈，避免产生重复，推荐您先通过自行搜索的方式查询是否存在类似问题。 |
| 19 | + |
| 20 | +* **在提交问题报告时请尽可能的尝试提供更多详细信息。** |
| 21 | + |
| 22 | + 由于产生的错误信息各不相同，其中一部分错误在几乎所有设备上都能遇到，而有一部分是因为某些特定情况甚至是硬件本身导致，所以我们推荐您在提交问题时提供尽可能多且详细的信息，以下为示例模板： |
| 23 | + |
| 24 | + * 服务器的日志文件（若服务器可用时），您则可用通过以下方式获取日志文件： |
| 25 | + * `/spark` |
| 26 | + * `[您的服务端所在文件夹]/logs/latest.log` |
| 27 | + * 你的设备规格参数 (包括您客户端的类型，操作系统平台，服务器硬件参数等), |
| 28 | + * 重现步骤 (您在遇到BUG之前进行了什么操作等), |
| 29 | + * 如果可以的话，请提供视频或截图加以辅助。 |
| 30 | + |
| 31 | +* **当被要求提供更多有关信息时。** |
| 32 | + |
| 33 | + 在某些情况下，某个错误可能会难以复现等，当上面反馈的信息都不能很好的帮助我们追踪问题时，在这种情况下，我们可能会要求您提供额外的信息以便更好的帮助追踪问题，并且我们一旦知道问题所在时，就会着手开始修复并与您取得联系。 |
| 34 | + |
| 35 | +* **提交改进意见时，请以简单易懂的方式描述它。** |
| 36 | + |
| 37 | + 有时传达您对某个功能的想法通常很困难，我们希望避免产生任何误解，因此，您在提交改进建议时，尽量使用简洁易懂的话语或方式描述您的想法。 |
| 38 | + |
| 39 | +* **避免发布"+1"重复问题。** |
| 40 | + |
| 41 | + 如果问题已经产生，并且你也遇到过但无法提供任何对我们有帮助的问题细节的话，那您可在相关问题下评论留言。 |
| 42 | + |
| 43 | + |
| 44 | +## <a id="Catalogs-Faq#2"></a>我想提交拉取申请! |
| 45 | + |
| 46 | +同时我们也欢迎各位开发者们对该项目作出您的贡献，您可在[问题追踪器](https://github.com/PowerNukkitX/PowerNukkitX/issues)页面发表您可以解决的问题等，同时我们也会使用[`Good First issue`](https://github.com/PowerNukkitX/PowerNukkitX/issues?q=is%3Aissue+is%3Aopen+label%3Agood%20first%20issue)标签标记出我们认为对新人有帮助的问题解答等。 |
| 47 | + |
| 48 | +⚠ 若您想参与该项目，则您需要注意一些事项： |
| 49 | + |
| 50 | +* **确保您对Java编程有一定的基础的同时，还需熟悉对IDE工具的使用等。** |
| 51 | + |
| 52 | + 虽然我们接受各种类型的贡献，但我们也有一定的代码质量要求，但我们审查您提交的代码时间是有限的，因此，我们希望避免提供入门建议等，如果您对Java编程不是很熟悉，我们建议您从一些个人项目开始，并熟悉语法，工具链等。 |
| 53 | + |
| 54 | +* **您需熟悉Git和Pull Request工作流程** |
| 55 | + |
| 56 | + [git](https://git-scm.com/) 是一个分布式版本控制系统，如果你不熟悉版本控制，一开始可能不是很直观。特别是，使用git的项目有一个特定的工作流程来提交代码修改，这被称为拉动请求工作(Pull Requests)流程。 |
| 57 | + |
| 58 | + 为了让事情进行得更顺利，我们建议你在网上查找一些资源，熟悉git的词汇和命令，并按照自己的节奏练习处理分叉和提交拉动请求。关于这个过程的高层次概述可以在[该文章](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests)中找到。 |
| 59 | + |
| 60 | + 我们还提供了一个[快捷链接](https://github.com/powernukkitx/powernukkitx/pulls)，用于向PowerNukkitX提出拉动请求。 |
| 61 | + |
| 62 | +* **确保提交的拉动请求是在相关分支上。** |
| 63 | + |
| 64 | + 如前文所述，特性分支可以帮助你将工作平行化，并将其与主要的 `Bleeding` 分支分开，另外也便于维护者的工作。在许多远程站点上使用多个 `Bleeding` 分支是很难跟踪的，而且很容易犯错，不小心推送到错误的 `Bleeding` 分支。 |
| 65 | + |
| 66 | +* **尽可能地为你添加的代码做测试。** |
| 67 | + |
| 68 | + 自动测试是高质量和可靠的代码库的一个重要组成部分。它们通过确保以各种方式重组（或重构）代码是安全的，来帮助使代码更具可维护性，同时也防止回归--在过去的某个时间点被修复后重新出现的错误。如果可行的话，请花时间添加测试，这样你所做的修改可以持续很长时间（希望如此）。 |
| 69 | + |
| 70 | +* **在打开拉动请求之前，先运行测试。** |
| 71 | + |
| 72 | + 与上一点相联系的是，有时代码库的一部分的变化会导致代码的其他部分的行为发生不可预测的变化。这就是为什么最好是在开启PR之前先运行测试。 |
| 73 | + |
| 74 | + 持续集成也会为你（和我们）运行测试，但最好不要依赖它，因为任何时候都可能有许多构建在排队。自己运行测试将帮助你更确定在点击 "创建拉动请求" 按钮时，你的修改已经准备就绪。 |
| 75 | + |
| 76 | +* **在打开拉动请求之前，请确保该请求是完整的。** |
| 77 | + |
| 78 | + 无论是修复错误还是实现新功能，你最好在点击*创建拉动请求*按钮之前，确保你要提交的修改尽可能完整。要跟踪一个拉动请求是否准备好接受审查，会给审查者带来额外的负担。 |
| 79 | + |
| 80 | + 草稿拉动请求是一种选择，但要在合理的范围内少用它们。它们最适合用来讨论那些不容易用自然语言描述的代码修改，或者对项目的未来方向有潜在的巨大影响。如果有疑问，不要打开草案，除非维护者要求你这么做。 |
| 81 | + |
| 82 | +* **只有当代码准备好了才推送。** |
| 83 | + |
| 84 | + 作为上述内容的延伸，当对一个已经开放的PR进行修改时，请尽量只推送你有合理把握的修改。每次提交后的推送都会导致持续自动构建队列的规模扩大，减缓工作速度，并占用可以用来验证其他修改的时间。 |
| 85 | + |
| 86 | +* **请确保选中*允许来自维护者的编辑*复选框。** |
| 87 | + |
| 88 | + 为了加快合并过程，合作者和团队成员有时会想自己向你的分支推送修改，对代码风格进行细微的调整，或者以其他方式重构代码，而不必煞费苦心地描述他们希望代码是什么样子。勾选 "允许维护者编辑 "复选框可以让他们这样做；如果没有这个复选框，他们就不得不向你报告问题并等待你来处理。 |
| 89 | + |
| 90 | +* **不要不断地将PR合并到主分支上。** |
| 91 | + |
| 92 | + 除非有合并冲突需要解决，否则没有必要一次又一次地把 `Bleeding` 合并到一个分支。反正在合并PR之前，其中一个维护者会自己合并 `bleeding`，而且持续的合并提交会使CI因排队等待过多的构建而不堪重负。 |
| 93 | + |
| 94 | +* **避免强行推送到PR分支。** |
| 95 | + |
| 96 | + 应该避免强行推送，因为这可能会导致意外地覆盖维护者的修改或CI构建错误的提交。我们重视项目中的所有历史，所以在大多数情况下没有必要压制或修改提交。 |
| 97 | + |
| 98 | + 需要强行推送的情况非常少见（比如不小心泄露了提交文件中的敏感信息，添加了不相关的文件，或者错误地合并了一个依赖的PR）。 |
| 99 | + |
| 100 | +* **在等待代码被审查和合并的过程中要有耐心。** |
| 101 | + |
| 102 | + 尽管我们希望尽可能快地审查所有的贡献，但我们的时间是有限的，因为团队成员除了审查代码外，还必须处理自己的任务。因此，工作需要被优先考虑，不幸的是，你的PR可能需要数天或数周才能被合并，这取决于它被认为是多么重要。 |
| 103 | + |
| 104 | +* **不要把对代码的批评误认为是对你个人的批评。** |
| 105 | + |
| 106 | + 如前所述，当涉及到项目时，我们对质量有高度的承诺。这意味着，来自经验不足的社区成员的贡献可能需要多轮审查才能达到可合并的状态。我们尽最大努力不把一个人和他所写的代码混为一谈，并且在任何时候都把讨论集中在代码上。请把我们的评论和要求看作是一种学习经验，不要把它当作是一种人身攻击。 |
| 107 | + |
| 108 | +* **我们随时欢迎您联系我们或寻求帮助。** |
| 109 | + |
| 110 | + 如果你对代码库的某些部分或游戏和框架的某些内部运作不确定，请通过在相关问题或PR中留言，或在[Discord](https://discord.gg/BcPhZCVJHJ)&[QQ群](https://jq.qq.com/?_wv=1027&k=6rm3gbUI)发文来联系我们。我们会尽可能地帮助你。 |
| 111 | + |
| 112 | + 说到哪种沟通方式最好，GitHub通常更适合长篇大论，而Discord和QQ群则更适合快速的呼唤和回应。在决定的时候，请尽力斟酌，并尽量将一个讨论放在一个地方，而不是来回移动。 |
| 113 | + |
| 114 | +## <a id="Catalogs-Swlang"></a>🌐 多语言文档 |
| 115 | + |
| 116 | +--- |
| 117 | +Need to switch languages? |
| 118 | + |
| 119 | +[](./CODE_OF_CONDUCT.md) |
| 120 | +[](../zh-hant/CODE_OF_CONDUCT.md) |
| 121 | +[](../../CODE_OF_CONDUCT.md) |
| 122 | +[](../../LICENSE) |
| 123 | +[](./CHANGELOG.md) |
| 124 | +[](https://doc.powernukkitx.cn) |
0 commit comments