如何让你的开源项目看上去像那么回事

题按：本文写给那些有志于加入到开源的世界的人们，主要以我的主力语言 Python 作为例子，但可适用于任何语言。

开源并不等于免费和开放源代码而已

相信各位搬砖工在公司里都有面对过屎山的经历，千奇百怪的编码风格、神出鬼没的注释和「卧槽，这也行」的骚操作充斥其间，我相信就算是 FLAGM 大厂也是如此。与之相反，如果你要将你的项目开源，对编码质量有很高的要求。而除了代码，一个开源的项目还有一些杂七杂八的东西，这些可能大家并不是很注意，但却能让你的开源项目「看上去像那么回事」。

一个漂亮的 README

README 是开源项目的门面，一个优秀的 README，至少要包含以下方面：

• 简单介绍项目是做什么的
• 项目有什么特点，吸引用户来用
• 安装、编译的方法
• 最简单的 Quick start 示例
• License

README 并不等同于文档（除非你没有专门的文档网站），它不需要详细到 API Reference，只需要几个简单，吸引人的例子，和安装使用说明。

其他可以给 README 加分的东西有：

• Badge，包括包管理、CI 状态、覆盖率、代码质量，这些都有 badge 可以用，可以到Shields.io选择你想要的，但不能放太多，6 个以下为宜。不能 README 没写多少，badge 一大坨。
• 一个图片或视频演示，相关工具及服务有：
  • Carbon或它的命令行版本——创建漂亮的代码高亮截图
  • Asciinema——创建终端动画视频
  • Termtosvg——录制终端动画为 svg 格式，也可以渲染成 Asciinema 的格式
• 一个可供用户预览的 Demo
  • 如果是应用类，可以做成网站放出
  • 如果是工具类，可以做成云 shell 的形式，有以下服务：
    • Repl.it
    • Google Cloud Shell
    • Google Colab——分享 Jupyter notebook
    • https://rootnroll.com——类似 Repl.it
    • Heroku 一键部署

其他 README 参考资源：

• https://www.makeareadme.com/

开源社区相关文件

要把你的项目开源，还有一些杂七杂八的文件，这些 GitHub 上的Community页面都有展示：

• LICENSE——最最最重要的，没放这个文件，别人是不能用你的源代码的。有 N 种许可证可以选，具体的差异不赘述，大部分情况我都是默认用 MIT。
• Code of conduct——行为准则，用于约束贡献者、用户及项目相关的讨论规范，避免一些不必要的争端，这个 GitHub 也有默认模板，或者去其他开源项目抄，都可以。
• CONTRIBUTING.md——贡献指南，包括如何设置开发环境，如何提交 issue，PR，如何跑测试，以及代码的规范等等。
• Issue template/PR template——Issue 和 PR 的提交模板，有太多用户不知如何提一个好的问题，经常信息不全、只言片语，就指望你为他排忧解难，怎么解？用水晶球吗？所以放一个完善的 Issue 模板，把待填的信息留空，可以很大程度避免这种情况。

项目代码相关文件

一千个人有一千种编码风格，除了在贡献指南中文字约定之外，我们还需要一些强制措施来保证代码的一致性。

• 持续集成——非常重要，如果你的开源项目没有 CI 的话会显得相当不专业，配置一个 CI 服务，把 Badge 贴到 README 里面，一目了然，持续集成包括

  • 自动化测试 Testing
  • 代码检查 Linting
  • 自动发布 Release

  可选择的服务有 TravisCI, Jenkins, Appveyor, Azure Pipelines, GitHub Actions。其中（个人认为）功能最强大的是 Azure Pipelines，但最容易上手的是 GitHub Actions，在这里我最推荐 GitHub Actions。

  持续集成通常用来兜底，作为 PR 通过的强制指标之一。

• Pre-commit ——主要用来代码格式化和运行 Linter，如果开发者安装了 pre-commit 钩子，这些动作会在提交前运行。虽然 Linting 经常包括在持续集成中了，但 Pre-commit 检查仍然有必要，且更快捷，能更早的发现问题，因为跑一次 CI 短则几分钟，长则能达到一小时，你肯定不想等这么久结果发现代码中有个错字吧。

• 各种 Linter, formatter 的配置文件，用来统一配置。我常用的此类工具有：

  • black——代码格式化
  • flake8——代码检查
  • isort——import 语句排序

• Editorconfig ——统一化一些编辑器的设定，包括换行符统一、编码统一、Tab/空格统一，终极争端解决器。当然前提是代码编辑器支持 Editorconfig。

对于一些需要工具支持的文件，需要在 CONTRIBUTING.md 中要求开发者安装。否则不给过 PR，哼。