每一个项目都 必须 包含一个 readme.md
文件,readme
里书写这个项目的简单信息。作用主要有两个,一个是团队新成员可从此文件中快速获悉项目大致情况,另一个是部署项目时可以作为参考。
1. 排版规范
- 中文文档请使用全角标点符号;
- 必须 遵循 Markdown 语法,勿让代码显示错乱;
- 原文中的双引号(” “)请代换成中文的引号(『』符号怎么打出来见 这里)。
- 所有的 「
加亮
」、「加粗」和「链接」都需要在左右保持一个空格。
2. 行文规范
readme.md
文档 应该 包含以下内容:
- 「项目概述」- 介绍说明项目的一些情况,类似于简单的产品说明,简单的功能描述,项目相关链接等,500 字以内;
- 「运行环境」- 运行环境说明,系统要求等信息;
- 「开发环境部署/安装」- 一步一步引导说明,保证项目新成员能最快速的,没有歧义的部署好开发环境;
- 「服务器架构说明」- 最好能有服务器架构图,从用户浏览器请求开始,包括后端缓存服务使用等都描述清楚(主要体现为软件的使用),配合「运行环境」区块内容,可作为线上环境部署的依据;
- 「代码上线」- 介绍代码上线流程,需要执行哪些步骤;
- 「扩展包说明」- 表格列出所有使用的扩展包,还有在哪些业务逻辑或者用例中使用了此扩展包;
- 「自定义 Artisan 命令列表」- 以表格形式罗列出所有自定义的命令,说明用途,指出调用场景;
- 「队列列表」- 以表格形式罗列出项目所有队列接口,说明用途,指出调用场景。