如何为开源项目和社区做贡献 -- 你应该知道的十件事（四）——如何创建自己的开源项目？

问题四：如何创建自己的开源项目？

? 在前文中，我们已经介绍了最常见的给开源项目做贡献的两种途径，但随着你做开源项目的深入，你可能就会发现一个新的方向并推出自己的开源项目，下面，我将结合我的讲演，向大家分享一下创建开源项目的经验。

1. 学习成功的开源项目

? 在GitHub上，有很多优秀的开源项目，对于新入门开源项目的小伙伴来说，学习并模仿一些成功的开源项目是十分必要的，主要学习以下内容：

• 项目命名格式，包括项目名称、文件夹名称等等。
• 文件夹结构，模仿与你所做项目比较相似的项目，学习一下人家是如何组织文件结构的。
• README文件撰写，学习一下成功的项目他的项目README文件时如何组织的。
• 编程规范，开源项目要有很好的编码规范以及一致的代码风格，可以学习一下开源项目所使用的编程规范。

? 以上只是罗列了一些比较重要的内容，需要学习的内容还有很多，学习永远在路上。最好是能够将集百家之长，然后形成自己的风格，这样就可以在自己的各个项目中使用，下次再创建新的项目时直接套用模板即可。

2. 固定自己的模板

? 通过学习一些优秀的开源项目，我们可以找到这些项目的共性，然后结合自己的风格，形成自己的模板。通过我创建开源项目的经验，可以很明确的告诉大家，一定要找到一个或者是固定一个适合自己的模板，这对自己后续创建项目以及维护项目是十分重要的。在固定自己模板时，应重点关注以下几点：

• 项目结构：这一块主要是一个文件结构，在创建项目时，你要考虑一下你的项目都有哪些内容，需要那些文件夹，哪些内容放在哪个文件夹里，这些内容如果你一开始没有考虑好，后续调整会十分麻烦。
• 编程风格：这是十分重要的一块内容，做开源项目，一定要遵循开源代码风格，现在比较常见的是谷歌代码风格，你可以结合谷歌代码风格，然后根据自己的编程习惯，形成一套自己的编程风格。
• 文件格式：抛开代码文件不说，主要的就是技术文档文件，开源项目一定要使用Markdown(.md)格式文件，尽量不使用第三方插件；此外就是技术文档格式一定要规范，层次分明，如果项目比较关键的话，要有中英文版本。

? 通过模仿成功的开源项目，这样你就可以开始创建自己的开源项目了，相面我将会在此处讲讲开源项目中的几个关键内容。

3. README.md 撰写

? 首先是撰写README，当然这项工作是你已经完成了厂库搭建以及代码内容后进行的，属于项目的收尾阶段进行的工作。但是这确实极其重要的一步，README是对你项目的介绍，也是对外展示你项目的主要窗口，因此README文件的第一印象就会决定访问者对你的项目是否感兴趣，因此既要有实用的内容，也要做的好看。

? 此处我总结了一些README文件的撰写经验，首先第一点是README要包含哪些内容，主要有以下方面：

• 项目简介：在README的顶部，用简洁的语言描述你的项目是什么，做什么，以及为什么有用，这可以帮助读者快速了解项目的核心概念和目的。
• 项目徽章：使用徽章来展示项目的状态，如构建状态、代码质量、许可证等，这些徽章可以提供额外的信息，并增强项目的专业性。
• 安装和使用说明：提供清晰的安装和使用说明，包括必要的依赖项、配置步骤和示例代码，确保这些说明足够详细，以便新用户能够轻松地开始使用你的项目。
• 功能亮点：突出显示你的项目的主要功能和特性，以及它们如何解决用户的问题或需求。这有助于吸引潜在用户并展示项目的价值。
• 屏幕截图和演示：如果可能的话，添加屏幕截图、GIF动画或视频演示，以展示项目的实际效果和用法，这可以使你的项目更直观易懂，并激发用户的兴趣。
• API文档或链接：如果你的项目提供了API，确保在README中包含相关的API文档或链接。这可以帮助开发人员更好地理解和使用你的项目。
• 贡献指南：提供一个贡献指南，说明如何参与项目的开发、提交代码更改、报告问题等。这有助于建立一个积极的社区氛围，并鼓励其他人参与你的项目。
• 许可证：在README中明确指出项目的许可证类型，并提供许可证文件的链接。这可以确保用户了解他们使用你的项目的条件和限制。
• 联系方式：提供你的联系方式（如电子邮件、Slack频道等），以便用户或其他开发人员与你取得联系、提出问题或寻求支持。

? 以上这些内容看起来比较多，如果放在一个文件里，就会显得十分冗余，所以对于一些比较大型的项目，可以将其中的一部分包含详细内容的部分放置在另一个文件中，然后在README文件中提供条目以及链接，这样使用人员可以很容易找到相关的文档。

? 除了内容要全面之外，README还要做的美观、大气以及有条理，能够吸引人眼球，因此，你还要学习一下README文件的美化。其实对于我们程序员来说，README文档的美化并不是做的要多么花里胡哨，只要做的规整、清晰有条理即可，因此要善于使用小图标、标题等级等内容，让你的README文件变得十分有条理。

? 另外，为了更好地推广你的开源项目，你最好提供的README文件包括英文版以及中文版，这样对于一些其他国家的开发者也可以明白如何使用。下面链接是我推出并维护的一个开源项目的README文件，，该文件我也是在不断学习与改进中，仅供参考：

https://github.com/guojin-yan/OpenVINO-CSharp-API/blob/csharp3.0/README.md

4. CONTRIBUTING.md

? CONTRIBUTING文件是一个重要的文档，用于指导贡献者如何参与项目的开发和贡献，它包含了一系列准则、规则和建议，以确保贡献者能够顺利地参与项目，并且保持代码库的质量和一致性。下面简单介绍一下CONTRIBUTING主要包含哪些内容：

• 欢迎和介绍：在文件的开头，用友好的语言欢迎贡献者，并简要介绍项目的目标和背景。说明贡献的重要性，以及你期待的贡献类型。
• 行为准则：为你的项目制定一个行为准则，定义在项目中可接受和不可接受的行为。这有助于维护一个积极、尊重和支持的社区氛围。确保明确说明如何处理违规行为和报告问题的途径。
• 贡献流程：详细描述贡献的流程，包括如何提交问题、提出功能请求、创建拉取请求等。提供清晰的步骤和示例，以便贡献者能够轻松参与项目的开发。
• 编码规范和风格：定义项目的编码规范和代码风格要求，以确保代码的一致性和可读性。提供相关的文档或链接，以便贡献者了解并遵循这些规范。

以上就是一个简单的CONTRIBUTING内容，对于我们个人创建的小型项目来说，这已经足够使用了。

问题五：开源社区中的道德规范

? 虽然开源社区是自由的，但是它也有一些规则和准则需要遵守。这些规则和准则是为了确保社区的秩序和协作的顺利进行。例如，尊重他人的贡献、保持礼貌和尊重、遵守项目的许可协议等。这些规则和准则有助于维护一个积极、健康和协作的社区环境。所以在此处我重点重复一下在开源社区中所需要遵守的一些进本的道德规范。

• 第一点：检查重复
  ? 这里的重复包含很多内容，例如问题重复、项目重复、PR重复、文章重复等等。

  • 首先讲一下问题重复。假设您在本地计算机上安装并运行一个开源项目，但遇到了一个错误。或者您通读了文档并发现了缺失的步骤，您可能想提出一个问题来解决这个问题。但在执行此操作之前，必须检查是否提出了类似的（打开和关闭）问题或拉取请求，以避免重复。在 GitHub 上问题或拉取请求页面顶部的搜索栏中输入可能的关键字，以检查是否存在可能的重复。
  • 然后是项目重复。如果你有一个新的想法，准备大干一场，创建一个新的开源项目，你首先要做的第一点就是检查一下当前是否有人在做相同的开源项目。可以通过GitHub的关键字检索，查找类似的项目，看看你的想法是否有人已经做过了。如果有人已经做过了，你可以检查一下他所做的项目与你要做的有什么差异，你所做的项目内容可能是对他项目的改进、升级等。这样的话，如果你需要创建一个新的项目，你最好可以跟原作者进行沟通，表明自己的想法，然后再创建时进行使用别名。
  • 接着就是PR重复。如果你发现开源项目的一些问题你是能够解决的，这时你就需要通过提交PR的方式进行提交，但是在提交前，你需要做一步检查，第一点检查一下该问题是否有人已经领取，如果有人领取，但是领取人长时间没有提供回复、提供的PR你觉得存在问题或者你有更好的解决思路，那这样的话你可以在问题下留言，申请提交自己的PR。
  • 最后是文章重复，这里可以是技术文章或者是博客文章。但是，文章重复是禁止的，因为文章重复会被认为是抄袭，你可以有部分是重复的，例如技术介绍，这些不是关键部分内容，但是对于关键部分，一定不能重复。另外如果你觉得该文章比较好，你可以申请转载，在转载时注明文章来源即可。

• 第二点：行为礼貌和尊重
  ? 在开源社区，一定要学会尊重和礼貌，在请教或者回复别人时，一定要有礼貌并尊重他人。首先是再请教别人时，一定要先表示感谢，然后要全面地展示一下自己的问题，最后再次表示感谢，在话语中一定要礼貌。另外在回复别人问题时，也要保持一种谦卑的语气，闻道有先后，术业有专攻，所以并没有什么优越感，要认可和尊重他人的工作成果和贡献，无论是代码、文档、设计还是其他形式的贡献，在适当的场合给予他人认可和赞誉。最后就是在自己的文章中也要保持基本的礼貌，不要含沙射影，不要谈论政治，不要涉及政治、宗教或其他具有争议性的话题，专注于项目的目标和愿景，确保所有人都能在一个中立的环境中参与和贡献。

• 第三点：协作和分享
  ? 首先是要学会帮助他人，如果你看到有人需要帮助或提问，尽量提供帮助。因为开源社区大佬很多，你帮助了他，在未来他可能也会帮助你，而且付出总会有回报，因此不要吝啬自己的帮助。另外要学会分享知识与经验，积极与社区成员分享你的经验和知识，你所经历的事情在未来别人可能也会经历，因此学会把你的经验分享出去，避免更多人踩坑。

• 第四点：保证质量和追求卓越
  ? 高质量的项目更容易获得用户和开发者的信任，当用户知道项目维护良好、少有bug，他们更愿意使用和推荐这个项目，这种信誉是开源项目成功的关键因素之一。并且随着项目质量的提高，用户基础和社区规模往往也会增长，质量高的项目更有可能持续发展，因为它们提供了一个稳固的基础，可以在其上构建新功能和改进。因此，我们要学会保证质量和追求卓越。

  • 首先，要制定清晰的贡献指南，说明如何提交贡献、代码风格、测试要求等，帮助维护代码质量和一致性。实行代码审查制度，让其他开发者检查新的提交，以发现潜在的错误、改进代码质量，并确保新代码符合项目的标准。并且利用自动化测试来确保代码改动不会破坏现有功能。这包括单元测试、集成测试、系统测试和性能测试。
  • 其次，就是提供详尽的文档，包括安装指南、使用教程、API文档和开发者指南，让用户和开发者容易理解和使用项目。并且使用问题跟踪系统来管理bug报告和功能请求，保证所有问题都被记录和跟踪，使用版本控制系统如Git，并采取适当的分支策略来管理代码的不同版本和功能开发。
  • 最后就是鼓励和促进社区成员之间的交流，通过讨论和协作来提高项目质量，要学会认可社区贡献者的工作，提供激励措施（如贡献者列表、感谢信等），以鼓励更多高质量的贡献。如果可以的话，可以提供开发者指南、教程和其他教育资源，帮助新成员更快地上手，并提升整个社区的技术水平。