什么是 CONTRIBUTING.md？

如何您希望有更多的人可以参与到自己的开源项目，那么您必须有一个 CONTRIBUTING.md。这些文件也称为贡献指南或软件贡献指南，是由项目所有者或管理者放置在免费开源软件包或其他开放媒体软件中的文本文件。该文件描述了任何人如何通过执行某些任务（例如代码格式化、测试修复甚至提交补丁）来参与项目。

GitHub 中有专门的 CONTRIBUTING.md 设置指南，可以参考：Setting guidelines for repository contributors

CONTRIBUTING.md 是为谁准备的？

此文件对三组人很有用。首先，寻求贡献的人，也就是开源项目的所有者或者运营者。因此最适合创建和维护 CONTRIBUTING.md。该文件将帮助您概述您期望其他人如何为项目做出贡献。

下一个受益者是贡献者，他们有兴趣知道他们可以处理哪些项目以及他们如何驾驭项目。

第三组，是项目的使用者。那些希望利用项目产品来处理或构建他们的项目的用户。

CONTRIBUTING.md 应该位于何处？

CONTRIBUTING.md 应与 README.md 和 LICENSE 一起放在根目录中。如果您尚未定义可能的贡献机制，请考虑创建一个带有“即将发布消息”的草稿 CONTRIBUTING.md 文件，告知潜在贡献者您打算征求他们的意见。包括项目负责人的联系信息以便跟进。

CONTRIBUTING.md 将在您的项目中展示，因此拥有一个干净、有序和受欢迎的项目结构是很重要的。

CONTRIBUTING.md 文件中应包含的内容

请考虑在 CONTRIBUTING.md 文件中包含以下组件。

  1. A welcome note 欢迎辞
    让贡献者知道你热衷于让他们加入，并期待与他们合作。
  2. Table of Contents 目录
    为了让贡献者能够轻松地跳转到他们感兴趣的部分，请考虑使用目录。每个标题都应该有其 URL 链接。若要在 Markdown 中执行此操作，请使用 [] 并在括号中加上标题，格式为：[标头名称]（#header 名称）。
  3. Provide Links 提供链接
    包括指向项目中不同项所在位置的指示以及可能对参与者有用的资源的链接，例如：
    • Links to resources 资源链接：如重要文档、bug、通信页面等
    • Templates 模板：模板提供了一种结构化格式，使用户更容易记录详细信息，项目经理也更容易快速分析信息。包括指向模板的超链接，例如错误报告和增强建议模板。通过使模板可下载，使用户能够轻松离线使用模板。
    • Test location 测试位置：链接到测试在目录中的位置。
    • Submit changes link 提交更改链接：指导用户如何进行和提交更改。包括有关他们可能会得到什么样的响应，以及他们可能等待响应多长时间的信息。
    • Development environment details 开发环境详细信息：这将指导用户如何设置其开发环境。如果 README.md 中已存在详细信息，请在 CONTRIBUTING.md 中也包含链接。
  4. Include “How To” details 包括“操作方法”详细信息
    通过以“操作方法”(How To)说明的形式提供有关如何导航项目的说明，使用户能够轻松做出贡献。请考虑包括以下内容：
    • How to make a bug report 如何进行错误报告：指导用户如何报告项目中的问题。使过程尽可能简单，预测挑战并提供解决方案的链接。通过提供响应问题的链接来整理该部分，例如已报告的错误列表，以便用户可以检查他们想要报告的内容是否已提前报告，分步“操作方法”、“错误跟踪器”、“常见问题解答”、链接以及任何其他将帮助用户进行错误报告。
    • How to fix a bug 如何修复 bug: 一些用户可能希望修复 bug，以及报告它。提供有关允许用户修复的 bug 类型的一些指南，以及包含不同脚本、问题和拉取请求标签示例的样式指南，会很有帮助。
    • How to suggest enhancements 如何建议增强功能：提供有关用户如何提交增强功能建议的指南。此类建议可能包括新功能或功能改进。为用户提供指向指南的链接，这将有助于您作为维护者和社区理解他们的建议。
      包括指向相关建议、调试指南和项目的最新版本的链接，用户可以访问这些链接，以查看他们打算建议的增强功能是否已以其他方式解决或实现。鼓励用户尽可能详细地介绍他们的建议，并提供指向增强建议模板的链接，以获取结构化和详细的建议。鼓励他们通过提供对项目配置设置的访问来测试他们的增强功能是否获得所需的行为。
    • Coding conventions and Style guide 编码约定和样式指南：约定 git commit message 的格式，让用户知道在项目中使用的时态、语气、字符数和其他样式格式。例如，您可以指示用户仅使用现在时，限制第一行的字符数，甚至是否允许使用表情符号，以及如何包含它们。解决如何引用问题、拉取请求以及如何在 CONTRIBUTING.md 的这一部分中包含某些代码。
      使用不同的脚本、文档或规范样式指南提供代码示例，以指导用户使用您在项目中使用的编码约定。
  5. Other Components 其他组件
    就项目中的交互而言，这些是说明项目管理和您的责任的组件。旨在让用户感到舒适地与您合作。考虑包括：
    • Code of Conduct 行为准则：您可能希望将这一部分作为 CONTRIBUTING.md 的一部分，为贡献定下基调。行为准则也可以是 CONTRIBUTING.md 或 LICENSE 中链接的单独 Markdown 文件。
    • Recognition section 认可部分: 为贡献者创建一个“感谢”部分，列出他们可能因在您的项目中的投入而获得的任何认可。
    • Project owner and contributors information 项目所有者和贡献者信息：通过列出核心贡献者、如何联系他们或链接到根目录中的 humans.txt 文件，让人们知道他们正在与谁合作，即人类，而不是机器人，使项目具有人情味。
    • Where can I get help? 我可以在哪里可以得到帮助？：具有指向响应问题的可靠沟通渠道的链接的扩展可能是一个有用的包含，因为它表明您对用户在项目中可能面临的挑战感兴趣，并为您提供了从用户的角度审查您的工作的机会。

您可以使用这个 contributing-gen 项目来生成您的 CONTRIBUTING.md。