[译]规范
原文地址:Specification
引言
README
必须满足下面列出的所有要求
注意:标准自述文件是为开源库设计的。尽管它在历史上是为
node
和npm
项目创建的,但它也适用于其他语言的库和包管理器
要求:
- 称为
README.md
(大写) - 如果项目支持i18n,则必须相应地命名该文件:
README.de.md
,其中de
是BCP 47语言标记。对于命名,请优先考虑语言的非区域子标记。如果只有一个README
且语言不是英语,则允许文本中使用不同的语言而无需指定BCP
标记:例如README.md可以是德语。在包含多种语言版本的情况下,README.md
固定为英语 - 是一个有效的
Markdown
文件 - 章节必须按下面给出的顺序出现。可省略可选部分
- 除非另有说明,否则每个章节必须具有下面列出的标题。如果
README
是另一种语言,则必须将标题翻译成该语言 - 不能包含无法访问链接
- 如果有代码示例,则应该像在项目的其余部分中对代码进行
linted
一样对它们进行linted
内容列表
注意:这只是规范的导航指南,并不是任何符合规范的文档定义或强制使用术语
- 章节
- 标题(
Title
) - 横幅(
Banner
) - 徽章(
Badges
) - 简短说明(
Short Description
) - 详细描述(
Long Description
) - 内容列表(
Table of Contents
) - 安全(
Security
) - 背景(
Background
) - 安装(
Install
) - 用法(
Usage
) - 附加内容(
Extra Sections
) - 应用编程接口(
API
) - 主要维护人员(
Maintainers
) - 致谢(
Thanks
) - 参与贡献方式(
Contributing
) - 许可证(
License
)
- 标题(
- 定义
章节
标题
- 状态(
status
):必须 - 必要条件(
requirements
):-
标题必须与
repository、folder
和package manager
名称匹配,或者它可以有另一个相关的标题,旁边的repository、folder
和package manager
标题用斜体字和括号括起来。例如:```
Standard Readme Style (standard-readme)
`` 如果任何文件夹、存储库或包管理器名称不匹配,则在详细描述中必须有一条说明原因 * 建议(
suggestions`):符合内容要求,做到显而易见
-
横幅
- 状态:可选
- 必要条件:
- 不能有自己的标题
- 必须链接到当前存储库中的本地图像
- 必须直接出现在标题后面
徽章
- 状态:可选
- 必要条件:
- 不能有自己的标题
- 必须用换行符分隔
- 建议:使用http://shields.io或类似服务创建和托管图像
简短说明
- 状态:必须
- 必要条件:
- 不能有自己的标题
- 小于
120
个字符 - 以
>
开始 - 一定是单独一行
- 必须与包装管理器
说明
字段中的描述匹配 - 必须匹配
github
的描述(如果在github
上)
- 建议(
js
相关):- 使用
gh description
设置并获取github
描述 - 使用
npm show . description
显示本地npm
包中的描述
- 使用
详细描述
- 状态:可选
- 必要条件:
- 不能有自己的标题
- 如果任何文件夹、存储库或包管理器名称不匹配,必须在此处说明原因。参考标题
- 建议:
- 如果太长,考虑移动到背景章节
- 介绍构建存储库的主要原因
-
应该用宽泛的术语来描述模块,一般只在几段中;模块的例程或方法、冗长的代码示例或其他深入的材料的更多细节应该在后面的章节中给出。
理想情况下,稍微熟悉模块的人应该能够刷新他们的内存,而不必点击“向下翻页”。当读者继续阅读文档时,他们应该会逐渐获得更多的知识。
内容列表
- 状态:必须;对于小于
100
行的README
是可选的 - 必要条件:
- 必须链接到文件中的所有markdown章节
- 必须从第二节开始;不要包含标题或目录标题
- 必须至少有一个深度:必须捕获所有二级标题(
##
)
- 建议:
- 可以捕获三级(
###
)和四级(####
)深度的标题。如果是长目录,这些是可选的
- 可以捕获三级(
安全
- 状态:可选
- 必要条件:
- 如果有必要强调安全问题,则说明。否则,它应该在
Extra Sections
- 如果有必要强调安全问题,则说明。否则,它应该在
背景
- 状态:可选
- 必要条件:
- 涵盖动机
- 覆盖抽象依赖项
- 涵盖知识来源:
see also
也很合适
安装
- 状态:默认是必须的,对于文档仓库而言是可选的
- 必要条件:
- 使用代码块说明如何安装
- 子章节(
subsections
):- 依赖(
dependencies
):如果有不寻常的依赖项或依赖项必须手动安装,必须提出
- 依赖(
- 建议:
用法
- 状态:默认是必须的,对于文档仓库而言是可选的
- 必要条件:
- 使用代码块说明常见用法
- 如果兼容于
cli
,用代码块说明其用法 - 如果可导入,用代码块表示导入功能和用法
- 子章节:
CLI
:如果命令行功能存在则是必要的
- 建议:
- 覆盖可能影响使用的基本选项:例如,如果是
javascript
,则覆盖promises/callbacks
(对ES6
而言) - 可以指向示例代码的可执行文件
- 覆盖可能影响使用的基本选项:例如,如果是
附加内容
- 状态:可选
- 必要条件:
- 无
- 建议:
- 这不应称为附加内容。可容纳
0
个或多个章节,每个章节必须有其标题 - 这应该包含任何其他相关的内容,放在用法之后,应用程序接口之前
- 具体来说,如果安全章节不够重要,不需要放在上面的话,可以放在这里
- 这不应称为附加内容。可容纳
应用编程接口
- 状态:可选
- 必要条件:
- 描述开放的函数和对象
- 建议:
- 描述签名、返回类型、回调和事件
- 覆盖类型不明显的地方
- 描述注意事项
- 如果使用外部
api
生成器(如go-doc、js-doc
等),那么指向外部api.md
文件即可
主要维护人员
- 状态:可选
- 必要条件:
- 列出存储库的维护人员,以及联系他们的一种方式(例如
github
链接或电子邮件)
- 列出存储库的维护人员,以及联系他们的一种方式(例如
- 建议:
- 这应该是一个负责这个仓库人员的小名单。这不应该是所有拥有访问权限的人,例如整个组织,而是应该
ping
并负责管理和维护存储库的人 - 列出过去的维护者是友好的
- 这应该是一个负责这个仓库人员的小名单。这不应该是所有拥有访问权限的人,例如整个组织,而是应该
致谢
- 状态:可选
- 必要条件:
- 必须称为
Thanks, Credits
和Acknowledgements
的其中一种
- 必须称为
- 建议:
- 陈述任何对项目开发有重大帮助的人或事
- 列出公共联系人的超链接(如果可以的话)
参与贡献方式
- 状态:必须
- 必要条件:
- 说明用户可在哪里提问
- 说明是否接受
PR
- 列出参与的任何要求;例如,对提交进行审核
- 建议:
- 如果有的话,链接到
CONTRIBUTING
文件 - 尽可能友好
- 链接到
github
问题库 - 链接到行为准则(
Code of Conduct
)。Coc
通常位于贡献部分或文档中,或者设置在整个组织的其他位置,因此可能不需要在每个存储库中包含整个文件。但是,强烈建议始终链接到代码,无论它位于何处 - 也可以在这里增加一个小节,列出贡献者
- 如果有的话,链接到
许可证
- 状态:必须
- 必要条件:
- 建议:
- 链接到本地存储库中较长的许可证文件
定义
提供这些定义是为了理清上述使用的任何术语
- 文档仓库(
Documentation repositories
):仓库中没有任何功能代码,比如RichardLitt/knowledge