如何编写好的README

github上了上传了许多仓库,如何更好的管理、使用这些仓库,其中关键的一点在于README的编写。README的目的是向使用者展示仓库的使用方法、来历以及未来的进展。越来越重视写好一个REAMDE优秀的工程不一定有一个好的README,但是不好的REAMDE一定不是一个优秀的工程

关于这个问题在网上也有许多讨论:如何写好Github中的readme?。当前主要参考了一个关于如何编写标准READMEgithub仓库:RichardLitt/standard-readme

内容列表

下面首先讲解standard-readme提供了README文件编写规范,并结合网上讨论进行相应的调整,然后使用README生成器yo,最后编写一些适应不同场景的README模板

规范

standard-readme提供了一个编写规范,原文和翻译如下

里面提出了README的章节列表:

  • 标题(Title,必须)
  • 横幅(Banner,可选)
  • 徽章(Badges,可选)
  • 简短说明(Short Description,必须)
  • 详细描述(Long Description,可选)
  • 内容列表(Table of Contents,必须)
  • 安全(Security,可选)
  • 背景(Background,可选)
  • 安装(Install,默认必须,对文档仓库而言可选)
  • 用法(Usage,默认是必须的,对于文档仓库而言是可选的)
  • 附加内容(Extra Sections,可选)
  • 应用编程接口(API,可选)
  • 主要维护人员(Maintainers,可选)
  • 致谢(Thanks,可选)
  • 参与贡献方式(Contributing,必须)
  • 许可证(License,必须)

从上到下按需实现相应章节内容,其中横幅指的是仓库logo,内容列表指的是后续章节标题,而不是工程架构

横幅

网上有很多在线设计logo的网站,不过下载是要收费的

找了一个免费的logo设计网站:logoly

协议

参考Adding a license to a repository

可以在线添加新文件,输入文件名为LICENSELICENSE.md,选择一个license模板,预览后提交即可

如果要更换协议,直接删除新建一个即可

自定义

standard-readme提供了相对完整的README章节架构,结合网上讨论和实际使用经验,再增加以下4个章节:

  • 中英文
  • 徽章
  • 版本更新日志
  • 待办事项

并更新章节参与贡献方式(Contributing

中英文

  • 状态:默认是必须的,对于文档仓库而言是可选的
  • 必要条件:
    • None
  • 建议:
    • 准备中英文两份README,相互之间可跳转
    • README.md为英文内容,README.zh-CN.md为中文内容
    • 放置在徽章之后,简短说明之前

徽章

  • 状态:可选
  • 必要条件:
    • 标题为徽章
  • 建议:

规范中已经提到了一个徽章章节,里面添加的是仓库编写、部署过程中使用的工具、规范等相应的徽章,而本章节在于给出自己仓库的专属徽章

徽章生成参考自定义徽章;章节内容参考RichardLitt/standard-readme

版本更新日志

待办事项

  • 状态:可选
  • 必要条件:
    • None
  • 建议:
    • 列出后续待完成的事项
    • 按实现顺序从上到下排列

参与贡献方式

在参与贡献方式章节中应该明确是否允许合并请求,并给出进行版本管理的相应规范,比如

完整内容列表

综上所述,完整的内容列表如下:

  • 标题(Title,必须)
  • 横幅(Banner,可选)
  • 徽章(Badges,可选)
  • 中英文(Chinese and English,默认是必须的,对于文档仓库而言是可选的)
  • 简短说明(Short Description,必须)
  • 详细描述(Long Description,可选)
  • 内容列表(Table of Contents,必须)
  • 安全(Security,可选)
  • 背景(Background,可选)
  • 徽章(Badge,可选)
  • 安装(Install,默认必须,对文档仓库而言可选)
  • 用法(Usage,默认是必须的,对于文档仓库而言是可选的)
  • 附加内容(Extra Sections,可选)
  • 应用编程接口(API,可选)
  • 版本更新日志(CHANGELOG,可选)
  • 待办事项(TODO,可选)
  • 主要维护人员(Maintainers,可选)
  • 致谢(Thanks,可选)
  • 参与贡献方式(Contributing,必须)
  • 许可证(License,必须)

生成器

参考:README生成器

模板

参考:

README_TEMPLATES/

example-readmes

以仓库zjZSTU/PyNet为例,生成不同适用范围的自定义模板。README模板地址:templates

最小README

建立一个最简单基本的README,仅包含必须的章节内容,参考MINIMAL_README.md

  • 标题(Title,必须)
  • 中英文(Chinese and English,默认是必须的,对于文档仓库而言是可选的)
  • 简短说明(Short Description,必须)
  • 内容列表(Table of Contents,必须)
  • 安装(Install,默认必须,对文档仓库而言可选)
  • 用法(Usage,默认是必须的,对于文档仓库而言是可选的)
  • 参与贡献方式(Contributing,必须)
  • 许可证(License,必须)

标准README

完整的实现所有章节内容,参考STANDARD_README.md

坚持原创技术分享,您的支持将鼓励我继续创作!