开源项目的 README 是项目的第一张名片,对于开源项目的用户快速了解与使用我们的开源项目至关重要。我们可以通过图、文、Gif 动画、视频等表现形式来丰富 README 的内容。
在 README 顶部,可以放置该项开源目的Slogan和项目的Logo。
为项目撰写一段言简意赅的介绍文案,让读者在3 分钟 内了解你的项目能做什么,应用于什么场景,能帮助用户解决什么问题。我们通常还可以添加一个功能列表,以及并添加一个链接到访问者可能不熟悉的参考资料。也可以在这里添加一个功能列表或一个背景小节。如果你的项目有替代方案,这也是列出区别因素的好地方。
常见的软件安装方式例如 Yarn、NuGet 或 Homebrew 通常可以通过几条命令快速完成安装。然而,考虑到阅读 README 的人可能是个小白用户,希望得到更多的指导。列出具体步骤有助于消除歧义,可以帮助用户快速下载和安装我们的项目。如果它需要特定的环境下运行,如特定的编程语言版本或操作系统,以及在指定公有云或者基于 Kubernetes 安装,也需要提供超链接外链到相关安装文档。
我们通常可以使用折叠的方式来隐藏较为复杂的内容,用户可以选择性地展开查看更详细的内容。
尽可能提供几个快速入门的使用示例,并展示预期输出,帮助用户在几分钟内快速上手你的项目,请参考 快速上手指南 了解更多。
清晰地告诉用户可以到哪里去寻求帮助,包括但不限于 GitHub issue、社群(如 Slack、Gitter)、电子邮件地址等方式。
说明我们的项目是否对贡献者开放,以及接受社区贡献的 Pull Request 要求是什么,例如是否需要签署 CLA,是否需要参考和遵循哪些代码与文档规范。请参考 贡献者指南 了解更多。
请参考 Code of Conduct(本项目遵守的行为规范)。
请在 README 底部声明此开源项目所采用的开源许可证。
- 项目主Repo的根目录下是否有Readme文件(文件名可以多样)
- Readme文件是否包含了如下部分
- 项目介绍
- 到quickstart/contributing/coc/license的链接
- 项目介绍是否通俗易懂