Skip to content

Latest commit

 

History

History
46 lines (25 loc) · 2.51 KB

readme_guide.md

File metadata and controls

46 lines (25 loc) · 2.51 KB

README 规范与建议

开源项目的 README 是项目的第一张名片,对于开源项目的用户快速了解与使用我们的开源项目至关重要。我们可以通过图、文、Gif 动画、视频等表现形式来丰富 README 的内容。

项目品牌

在 README 顶部,可以放置该项开源目的Slogan和项目的Logo。

项目介绍

为项目撰写一段言简意赅的介绍文案,让读者在3 分钟 内了解你的项目能做什么,应用于什么场景,能帮助用户解决什么问题。我们通常还可以添加一个功能列表,以及并添加一个链接到访问者可能不熟悉的参考资料。也可以在这里添加一个功能列表或一个背景小节。如果你的项目有替代方案,这也是列出区别因素的好地方。

安装说明

常见的软件安装方式例如 Yarn、NuGet 或 Homebrew 通常可以通过几条命令快速完成安装。然而,考虑到阅读 README 的人可能是个小白用户,希望得到更多的指导。列出具体步骤有助于消除歧义,可以帮助用户快速下载和安装我们的项目。如果它需要特定的环境下运行,如特定的编程语言版本或操作系统,以及在指定公有云或者基于 Kubernetes 安装,也需要提供超链接外链到相关安装文档。

我们通常可以使用折叠的方式来隐藏较为复杂的内容,用户可以选择性地展开查看更详细的内容。

快速入门

尽可能提供几个快速入门的使用示例,并展示预期输出,帮助用户在几分钟内快速上手你的项目,请参考 快速上手指南 了解更多。

支持

清晰地告诉用户可以到哪里去寻求帮助,包括但不限于 GitHub issue、社群(如 Slack、Gitter)、电子邮件地址等方式。

参与贡献

说明我们的项目是否对贡献者开放,以及接受社区贡献的 Pull Request 要求是什么,例如是否需要签署 CLA,是否需要参考和遵循哪些代码与文档规范。请参考 贡献者指南 了解更多。

Code of Conduct

请参考 Code of Conduct(本项目遵守的行为规范)

许可证

请在 README 底部声明此开源项目所采用的开源许可证。

Readme的Checklist

  • 项目主Repo的根目录下是否有Readme文件(文件名可以多样)
  • Readme文件是否包含了如下部分
    • 项目介绍
    • 到quickstart/contributing/coc/license的链接
  • 项目介绍是否通俗易懂