如何写一篇规范完整的 README?
作为一个程序员, 为自己的项目或仓库撰写 README 是必不可免的工作. 一个好的规范的 README 文件可以让其他人快速准确地理解你的仓库代码, 快速地安装并使用, 并在必要的时候知道如何与你合作, 对开源项目的传播有极大的帮助.
那么该如何撰写一份规范简介的 README 文件呢? 一个标准的 README 文件又该具备哪些部分? 如果你同样有这些疑问, 请仔细阅读本文, 我相信会给你很大的帮助.
什么时候写?
README 文件必须在别人能访问到项目或仓库之前准备好. 在新建项目时就为项目同时新建好 README 文件是一个良好的开发习惯, 它应该是所有项目仓库提交的第一个文件.
放在什么地方?
通常情况下放在项目的根目录底下, 因为这是别人第一次访问你的项目或仓库时最先进入的地方. GitHub 和 GitLab 等平台会默认自动寻找你项目中的 README 文件, 并将其展示在你的项目目录底部.
如何撰写?
文件类型
虽然从理论上来说, README 文件可以是任何能显示 txt 的文件格式, 但是最常用的还是 Markdown 格式.
模板格式
我们先来看一个比较简单的 README 文件, 这是一个最简单的模板. 由于每个项目的不同, 你不一定要遵循该模板, 在本文后面的部分我们会对模板中必要的部分进行讲解和讨论.
README.md Demo
Foobar
Foobar is a Python library for dealing with word pluralization.
Installation
Use the package manager pip to install foobar.
pip install foobarUsage
import foobar
# returns 'words'
foobar.pluralize('word')
# returns 'geese'
foobar.pluralize('goose')
# returns 'phenomenon'
foobar.singularize('phenomena')Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
License
必要的元素
由于每一个项目都是不同的, 所以很难给出一个标准的 README 的格式, 你必须根据自己的项目来对模板进行调整. 虽然通常来讲 README 不会非常冗长, 但是当你发现你写的 README 长度过长时, 应当考虑其他格式的文档, 而不是去删减 README 中的内容. 因为更详细的 README 一定好过太短的, 尽量确保他人需要知道的信息都包含在 README 中.
下面列举了一些 README 中非常必要的部分供大家参考.
名字(Name)
为你的项目或仓库取一个好名字是必不可少的. 一个好的名字必须拥有自解释性, 即他人看到这个名字就能明白该仓库的核心功能, 无需更多的解释.
描述(Description)
让人们知道你的项目具体能做什么. 提供上下文并添加到访问者可能不熟悉的任何参考的链接. 也可以在这里添加功能列表或背景子部分. 如果你的项目有其他相似的或可替换的项目, 这是一个列出与其他项目差异化因素的好地方.
徽章(Badges)
你可能在某些 README 文件中看到过一些徽章, 用来表示下载次数, 版本或者其他信息. 如果你没有见过, 那么我们这里所说的徽章就是指下面这个小东西:
如果你想在自己的 README 中添加这个, 那么 Shields.io 是一个不错的选择, 另外网络上还有很多其他的网站也都可用生成它们.
图像(Visuals)
为了让访客们更方便理解代码的执行效果, 在 README 中添加一些截图, 动图或者视频是非常好的选择. 有许多小工具可用帮助你, 例如 ttygif.
安装(Installation)
安装指导是 README 中 不可省略的. 通常需要列举出在不同环境中的详细安装过程. 请考虑访客是一个新手的可能, 尽可能地展示安装过程, 具体的步骤有助于消除歧义.
如果你的项目只能在特定的依赖中运行, 那么也需要在这里指出. 如果依赖非常复杂, 需要在 README 中添加额外的 Requirements 小节来进行解释.
使用(Usage)
给出一些小的使用案例, 并尽可能列出预期的输出. 如果可能的话, 给出复杂示例的跳转链接, 如果这些示例太长而无法被合理地包含在 README 中.
提供支持(Support)
告诉访问者如何能够联系你, 这样它们就可以向你寻求帮助或者为项目提供一些贡献.
计划(Roadmap)
如果你未来有更新的计划或者 TODO List, 也可以在 README 中列举出来.
贡献(Contributing)
说明你是否愿意接受捐款, 以及接受捐款的条件是什么.
对于想要更改项目的人来说, 有一些关于如何开始的文档是很有帮助的. 也许他们需要运行一个脚本, 或者需要设置一些环境变量. 明确这些步骤. 这些指导对你未来的自己也很有用.
你还可以记录命令以检查代码或运行测试. 这些步骤有助于确保高质量的代码, 并减少更改无意中破坏某些东西的可能性. 如果需要外部设置, 例如在浏览器中启动 Selenium 服务器进行测试, 那么提供运行测试的说明尤其有用.
作者及致谢(Authors and acknowledgment)
向那些项目的贡献者或者为你提供过帮助的人表示真诚的感谢, 可以在此处引用他们的博客主页或者 GitHub 主页.
认证(License)
对于开源项目来说, 需要附加 License. 如果你不知道怎么选择一个合适你的 License, 那么这个网站会帮助你: Choose an open source license.
项目状态(Project Status)
如果你已经没有精力或者计划继续维护这个项目, 请在 README 的顶部注明项目的开发已经完全停止. 如果你希望人们自愿作为维护者来介入来让项目继续下去也可以在这个小节发出请求.
变更记录(Changelog)
你可以在 README 中添加一个跳转到 Changelog 的链接, 详细记录项目各个版本之间的区别以及注意事项.
其他的文件形式
虽然 README 文件对于项目来说是必不可少的, 但是有很多时候也是不够用的. 有很多其他形式的文件将会帮助你更好地解释并推广你的开源项目.
相关资源
我相信你在查看很多 repo 的时候看到其中有许多动画, 头像或者其他美化的部分. 我在此附上一部分的资源链接, 如果你也想为自己的 README 增加一些装饰, 不妨使用以下资源.
相关信息
- Readme Typing SVG: 可以根据指定的一句话生成一个逐个字母打印出来的动画.
Typing SVG
- Profile Header Generator: 可以生成头图来强调
README的标题或装饰.github header image
- Skill Icons: 可以用代码为 markdown 文件插入常见的技术栈 logo, 用来标注
repo使用到的一些技术.Skill Icons
变更历史
最后更新于:
- 于 2024/11/21
- 于 2024/11/21
- 于 2024/11/20
- 于 2024/11/20
- 于 2024/11/20
- 于 2024/11/19
- 于 2024/11/13
- 于 2024/11/5
- 于 2024/11/4
- 于 2024/11/1
- 于 2024/11/1
- 于 2024/10/29
- 于 2024/10/17
- 于 2024/10/17
- 于 2024/10/14
- 于 2024/10/11
- 于 2024/9/24
- 于 2024/9/24
- 于 2024/9/23
- 于 2024/9/23
- 于 2024/9/20