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

题按：本文写给那些有志于加入到开源的世界的人们，主要以我的主力语言 Python 作为例子，但可适用于任何语言。 <!-- more --> 开源并不等于免费和开放源代码而已 相信各位搬砖工在公司里都有面对过屎山的经历，千奇百怪的编码风格、神出鬼没的注释和「卧槽，这也行」的骚操作充斥其间，我相信就算是 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，哼。