记住:是文档,而不是代码,定义了这是一个什么项目。

概述

编写并规范README自述文件的好处

  • 节约你我他的时间,让人一目了然项目的用途、用法等

  • 有利于项目的传播,吸引志同道合的朋友,让更多的贡献者(技术或捐助等)参与进来

  • 在上述基础上,可以使优秀的项目长期得到维护,不至于荒废

  • 添加了开源许可协议等声明,避免了日后可能的纷争

怎样才算是写好了README自述文件

当人们能够不用看你的项目代码就可以使用你的项目的时候,你的基本自述文件算是完成了。

基本要求

  1. 大写文件名且必须为Markdown文件,README.md
  2. 若支持i18n,则自述文件需要分别命名,需符合BCP 47的非区域子标记(Subtag),例如:README.ZH.md(中文),README.md 默认为英语
  3. 其中包含的链接需可访问,代码部分不能直接贴,需以代码块形式显示
  4. 自述文件有一定的书写顺序和必须包含的标题项,从上至下大致为:

  • 标题(一般与仓库名一致)
  • 横幅Logo(可选,相对路径链接到本地存储库图片或相应网站上等)
  • 徽标Badge(用换行符分隔)
  • 简短的项目描述(最好用一行即可描述清楚)
  • 详细说明,最好配流程图等(可选)
  • 内容列表/目录,带链接(可选,一般在篇幅较大时采用,目录从下一节开始且至少有一个深度,即含有子标题,目录较短的话可以有三到四个深度)
  • 这里是主体部分,主要描述项目背景、如何配置、安装和使用等,自由发挥
  • 致谢(可选)
  • 参与贡献方式(Contributing,一般链接到贡献文件和issues,可列出贡献者)
  • 许可证(License,声明许可证标识符或全名, 可链接到本地存储库的 LICENSE 文件并声明持有者)

参考资料

  1. 标准化README
留言评论
推荐阅读