Skip to content

Latest commit

 

History

History
236 lines (173 loc) · 7.84 KB

spec.zh-CN.md

File metadata and controls

236 lines (173 loc) · 7.84 KB
Raw

规范

一个兼容的 README 必须满足下面列出的所有需求。

注意: 标准自述文件是为开放源码库设计的。 尽管它以前是为 Node 和 npm 项目制作的，但它也适用于其他语言的库和包管理器。

要求:

  • 被叫做 README.md (大写).
  • 如果项目支持 i18n，文件名必须相应地命名: README.de.md, de 是 BCP 47语言标记. 对于命名，优先考虑语言的非区域子标记. 如果只有一个 README，并且语言不是英语，那么文本中允许使用不同的语言，而无需指定 BCP 标记: 例如: README.md 如果没有语言 README 的话，可以用德语 README.md. 在有多种语言的地方,README.md 是留给英语的.
  • 做一个正确的 Markdown 文件.
  • 部分必须按照下面给出的顺序显示。可以省略选择部分.
  • 除非另有说明，部分必须有下面列出的标题。 如果 README 是另一种语言，则必须将标题翻译成该语言.
  • 不能包含失效的链接.
  • 如果有代码示例，那么它们的连接方式应该与项目其余部分的代码连接方式相同.

目录

注意: 这只是规范的建议，并没有为任何符合规范的文档定义或强制要求使用术语。

段落

标题

状态: 必须

要求:

  • 标题必须与仓库、文件夹和包管理器名称相匹配——或者用斜体和括号表示的相关副标题。 例如:

    # Standard Readme Style _(standard-readme)_

    如果任何文件夹、仓库或包管理器名称不匹配，必须在“长描述”中附注说明原因。

建议:

  • 应该是有据可循的

横幅

状态: 可选

要求:

  • 不能有自己的标题
  • 必须链接到当前存储库中的本地映像
  • 必须直接出现在标题后面

徽章

Status: 可选.

要求:

  • 不能有自己的标题
  • 必须用换行符分隔

建议:

  • 使用 http://shields.io 或类似的服务来创建和托管图像
  • 添加 Standard Readme badge 徽章.

简短描述

状态: 必须

要求:

  • 不能有自己的标题
  • 必须少于120个字符
  • 不能以 > 开始
  • 一定是在它自己的行上
  • 必须符合包管理器的描述字段
  • 必须符合 GitHub 的描述(如果在 GitHub 上)

建议:

  • 使用gh-description 描述设置并获取 GitHub 描述
  • 使用npm show . description 来展示本地的描述 npm 包

长描述

状态: 可选

要求:

  • 不能有自己的标题
  • 如果任何文件夹、存储库或包管理器名称不匹配，则必须在这里说明原因。 看标题部分

建议:

  • 如果太长，考虑移动到背景部分。

  • 包含构建储存库的主要原因。

  • “这应该大致地描述你的模块，通常只有几个段落; 模块的例程或方法的更多细节，冗长的代码示例，或其他深入的材料应该在随后的章节中给出。 理想情况下，对您的模块稍微熟悉的人应该能够刷新他们的记忆，而不必按下“页面向下”键。 当你的读者继续阅读文档时，他们应该会接收到越来越多的知识。”

    ~ Kirrily "Skud" Robert, perlmodstyle

目录

状态: 必需的; 对于小于100行的 README 可选。 要求:

  • 必须链接到文件中的所有 Markdown 部分
  • 必须从下一节开始，不要包括标题或目录标题
  • 必须至少有一个深度: 必须捕获所有 ## 标题

建议:

  • 可以捕获第三个和第四个深度标题。如果是长目录，这些是可选的.

安全

状态: 可选.

要求:

  • 如果需要强调安全问题，可以在这里，否则应该在额外部分.

背景

状态: 可选

要求:

  • 包含动机.
  • 包含抽象依赖关系.
  • 包含知识来源: 可参见也很合适.

安装

状态: 默认情况下是必需的，文档存储库是可选的.

要求:

  • 说明如何安装的代码块

子段落:

  • 如果有不寻常的依赖项或依赖项，必须手动安装

建议: -链接到编程语言的必备站点: npmjs, godocs,等等.

  • 包括安装所需的任何系统特定信息.
  • 一个更新部分对大多数软件包都很有用, 如果用户可以使用多个版本.

用法

状态: 默认情况下是必需的，文档存储库是可选的.

要求:

  • 说明常用用法的代码块.
  • 如果 CLI 兼容，则代码块指示通用用法.
  • 如果可导入，则指示导入功能和用法的代码块.

建议:

  • CLI. 如果 CLI 功能存在，则需要.

建议:

  • 涵盖可能影响使用的基本选项: 例如，如果是 JavaScript，则涵盖 promises / callbacks，此处为 ES6
  • 如果相关，指向一个可运行的文件以获取使用代码

额外部分

状态: 可选.

要求:

  • 没有.

建议:

  • 这不应该被称为额外部分. 这是一个包含0个或更多部分的空间，每个部分都必须有自己的标题
  • 这应该包含任何其他相关的部分,放在用法之后, API 之前.
  • 具体来说，就是, 安全部分如果没有重要到可以放在上面的话，这个部分应该在这里.

API

状态: 可选

要求:

  • 描述暴露出的功能和对象.

建议:

  • 描述签名、返回类型、回调和事件.
  • 指明不容易理解的类型.
  • 描述注意事项.
  • 如果使用外部 API 生成器(比如 go-doc、 js-doc 等等) ，请指向外部 API.md 文件. 这可能是该节中的唯一项，如果存在的话

维护者

状态: 可选.

要求:

  • 一定要叫维护者
  • 列出存储库的维护人员，以及与他们联系的一种方式(例如 GitHub 链接或电子邮件).

建议:

  • 这应该是一个负责项目方向的人员名单。 这不应该是拥有访问权限的每个人，比如整个组织，应该被展示的人是负责存储库的指导和维护的人
  • 列出过去的维护人员对于属性和分类都有好处.

致谢

状态: 可选.

要求:

  • 一定要叫做 致谢 或者 感谢.

建议:

  • 说明对项目的开发有重要帮助的任何人或任何事情
  • 标明公共链接，如果适用的话

如何贡献

状态: 必需.

要求:

  • 说明用户可以提问的地方.
  • 说明是否接受 PR .
  • 列出贡献的所有要求; 例如，在提交时有一个签名.

建议:

  • 链接到如何贡献文件--如果有的话
  • 尽可能友好
  • 链接到 GitHub issues 区域.
  • 链接到行为守则. 如何贡献规范通常位于贡献部分或文档中,或者位于整个组织的其他位置，因此可能不需要在每个存储库中包含整个文件。 但是，强烈建议始终链接到规范位置，无论它位于何处.
  • 这里也欢迎列出贡献者的子段落.

许可证

状态: 必须

要求:

  • 声明许可证全名或标识符, 参考SPDX 许可证列表上的. 对于未授权的存储库, 添加 UNLICENSED. 更多详情，请参见 SEE LICENSE IN <filename> 并链接到许可文件. (这些要求是从 npm继承过来的).
  • 声明许可证持有人.
  • 一定是最后一部分.

建议:

  • 链接到本地存储库中较长的许可证文件

定义

提供这些定义是为了澄清上面使用的任何术语.

  • 文档存储库: 没有任何功能代码的存储库