CONTRIBUTING_cn.md

English | 中文

贡献指南

我们非常荣幸并感激您愿意为本项目做出贡献。

为确保您的努力能够顺利融入项目并惠及整个社区，我们制定这份指南，来帮助您更好地理解我们的标准和流程。

建议您认真阅读以下内容，它们旨在助您高效工作，并确保您的成果符合我们的要求和规范。

斜体部分属于建议，其余属于要求，均作为您开发过程中，及插件库维护者审酌 PR 时的参考。请特别注意加粗部分。

希望这份指南能成为您的良好起点！

添加或修改插件？

插件适合入库吗？

不要急于求成。在创作并提交新插件之前，思考如下问题：

• 你的插件是否为打包插件？——单文件插件和文件夹插件不可入库；
• 是否已经存在功能极度相似的插件？——无意义的重复轮子不可取；
• 你的代码是否有必要作为 MCDR 插件提供？是否更适合 PyPI？——考虑使用目的，确保它有必要；
• 插件泛用性是否足够？是否有足够的理由让新用户选择你的插件？——不要将仅供自用或完全不实用的插件提交到插件库；
• 你的项目准备好进入公众测试（Beta）阶段了吗？——如果它还处于早期版本，请先将其完善。我们建议您在提交时保证插件已有一个可用 Release。

版权意识很重要

为保证提交正确，我们希望您能符合以下身份之一：

• 插件的作者、维护者或是被授权的协作者；
• 获作者、维护者或协作者明确书面许可的上传者。

若您的插件中参考或包含其他项目的代码：

• 对于开源代码，请务必遵守相应的开源许可证；
• 使用闭源代码时，请确认自己拥有使用权，并严格遵守相关协议。

我们强烈建议您 使用开源许可，以保护您和他人的权利。插件库脚本和 MCDR 对您仓库执行的操作应与所有 OSI 批准的许可相兼容。

否则，请理解并知悉：

• 通过提交您的插件至插件库，您在专有协议或许可之外（如果有），授予任何实体直接或间接地从 Github Releases 下载和使用您插件的权利；
• 您的提交请求可能需要更长的处理时间。

前置工作要注意

• 插件名称和 ID 不要与其他插件太过相似；
  作为参考，一种量化标准为：转为小写的插件名称和 ID 与其他插件相应字段的 莱文斯坦距离 不应小于 3
• 在相应字段中显式声明前置插件和 Python 包，
  留意你的插件是否是用了新版本 MCDR 特有的接口，按需声明 MCDR 版本；
• 确保你的插件在目标平台上可以正常工作。

插件信息要写对

按照 文档 中的说明创建或编辑 plugin_info.json。

• 参照已有插件和文档，检查 label 字段是否合适；
• 插件 README 应当放置于 related_path 中且命名为 README.md（不分大小写）；
• 插件 ID 必须在各个环节保持一致；
• description 和 introduction 字段应当正确，至少提供一种语言。

插件介绍要写好

良好且详细的介绍是成为优秀插件的条件之一。

• 在 README 或文档中，详细阐释插件的环境要求、功能、特征、用法等；
• 在 description 中用一句话简单概括插件的作用；
• 在 introduction 中介绍插件的特点，或直接指向 README 文件。

一个 PR 一件事

• 添加插件时，请将多个插件分开 PR；
• 修改插件时，相同作者多个插件的相同字段修改可以合并在一个 PR 中；
• 删除插件时，相同作者的多个插件可以合并在一个 PR 中。

交了 PR 别着急

提交 PR 后，插件库维护者将尽快审酌您的插件。他们将根据自动检查结果、该指南和个人判断，给出相应的反馈。如果他们无法做出决定，您的 PR 可能交予上一级维护者处理。在这一过程中，您可以自行决定是否采纳他们的建议（如果有）。这些建议可能帮助您的插件更加顺畅地并入插件库。

发版本时要小心

参照 文档 发布插件版本。

• Release Tag 必须正确填写，否则插件库无法获取版本地址；
• 将打包插件（.mcdr 或 .pyz）作为附件上传。

贡献脚本或工作流？

• 建议先创建 Issue，描述问题或需求，再创建与之关联的 PR；
• 所有修改应当合并到 master 分支。

此文档最初使用 zh_cn 撰写。如有任何疑问，欢迎在 Issue 中提出。