README 是一种说明文件,包含有关软件项目、目录、数据集或其他文件集合的入门信息。它的名称意为“读我”,表明它是了解随附材料的起点。在软件项目中,README 是一种常见的软件文档,通常介绍软件的功能、安装和使用方法,以及获取更多信息的途径。
命名与格式
常见的文件名包括 README、README.txt 和 README.md。使用大写字母是一种惯例,并非强制要求。不过,在区分大小写的文件系统中,或对于查找特定文件名的工具而言,文件名的准确写法可能很重要。
README 通常存放在项目的顶层目录中,与源代码或分发文件放在一起。子目录中也可能包含额外的 README 文件,用于说明该目录的内容、特殊情况或操作流程。
README 文件采用多种格式:
- 纯文本:无需专门的渲染工具即可阅读,适合在终端和基本的文本编辑器中查看。
- Markdown 标记语言:通常使用
.md扩展名,支持标题、列表、链接、图片和代码块,同时仍便于作为纯文本阅读。 - reStructuredText:通常使用
.rst扩展名,支持结构化文档,并可与文档生成工具集成。 - 超文本标记语言:可提供更丰富的呈现效果,但不便直接在终端中阅读。
文件扩展名表明其预期采用的格式,但 README 并没有通用的结构规范。章节安排和措辞通常由项目维护者决定。
常见内容
README 用于帮助读者初步了解项目,而不是提供详尽的手册。其内容取决于目标读者和随附材料,但通常包括:
| 章节 | 常见用途 |
|---|---|
| 项目介绍 | 说明项目的目的、范围和主要功能 |
| 运行要求 | 列出支持的环境、依赖项和先决条件 |
| 安装 | 说明如何获取和配置软件 |
| 快速入门 | 提供一个最小可运行示例 |
| 使用方法 | 说明常用操作、命令或配置 |
| 文档 | 指引读者查阅教程、手册和参考资料 |
| 参与贡献 | 说明如何报告问题或提出修改建议 |
| 许可证 | 指明适用的许可证,并提供其全文的位置 |
| 项目状态 | 说明开发状态、维护预期或已知限制 |
对于程序库,快速入门部分可能会展示一段使用其应用程序编程接口的简短程序。对于采用命令行界面的工具,则可能展示一条命令及其预期输出。数据集的 README 则可能说明文件组织方式、字段含义、采集方法、计量单位和使用条件。
README 的详细程度因项目而异。一个小型实用工具可能只需一个文件就能说明清楚,而大型项目可能主要将 README 用作独立文档系统的导航页。
在开发与分发中的作用
README 文件的出现早于现代基于网络的开发平台。长期以来,它们一直随软件归档包和源代码发行包一同提供,使用户在复制或下载文件后仍能查阅相关说明。
在当代软件工程中,README 通常与代码一起保存在 Git(版本控制系统)等版本控制系统中维护。这样,文档的修改就可以与其所描述的实现变更一同接受审查并留下记录。因此,某一发行版所附的 README 可以针对该发行版提供说明,而不只是介绍最新的开发版本。
许多代码仓库托管服务会在仓库主页上自动展示所识别的 README。这使得该文件既是随项目分发的文档,也是面向网络读者的重要介绍页面。其在线展示的内容可能包括屏幕截图、示意图、状态徽章和外部文档链接。
README 在开源软件中尤其显眼,因为读者可能需要在不直接联系维护者的情况下评估和使用项目。私有仓库、内部工具、研究资料档案以及非软件类文件集合也会使用 README。
与其他项目文件的关系
README 通常用于介绍更专门的文档或指引读者查阅这些文档,而不是取代它们:
LICENSE或COPYING文件包含许可条款。README 中简短的许可证声明不一定完整重现这些条款。CONTRIBUTING文件说明开发和参与贡献的流程。CHANGELOG记录各发行版之间的重要变更。SECURITY文件可能说明受支持的版本和漏洞报告流程。- 参考手册和教程提供比入门材料更详细的信息。
README 也不同于机器可读的元数据。软件包管理器可能要求提供一个采用规定格式、包含依赖项声明和版本信息的清单文件。README 可以向读者解释这些要求,但通常不能取代该清单文件,也不能控制安装行为。
局限性
README 的实用性取决于其内容是否准确、覆盖范围是否恰当。随着项目变化,安装命令、支持的操作系统、示例和链接都可能过时。仓库当前开发分支中的文档,也可能与已安装的较旧发行版的实际行为不符。
渲染效果并不能在所有环境中保持一致。不同工具对 Markdown 方言、相对链接的处理、嵌入式 HTML 的限制以及图片的支持各不相同。在托管服务上显示正常的内容,在本地查看器或打包后的发行版中可能呈现出不同效果。
README 是文档,并不是对随附软件的验证。有关功能、兼容性或安全性的声明,本身并不能证明这些特性已经过测试。同样,README 中的命令和外部链接仍只是文件提供者给出的内容;这个文件名本身并不构成任何特殊的可信保证。