软件项目目录与文件管理规范
版次：2022年3月10日 第1版，最新更新日期：2023年2月15日
类型：程序文件
部门：软件部
上海维宏电子科技股份有限公司 版权所有
| 文件版本 | 修改前文件版本 | 主要修订内容和原有 | 修订人 |
|---|---|---|---|
| R3.1 | R3（郑之开 草稿版） | 1. 规范文档格式。 2. 去除 SRS 模板，独立成文件。 3. 翻译注释为中文。 4. 修改 SRS 部分。 |
祁彩云 |
| R3.2 | R3.1 | 1. doc 下新增 manual 目录。 2. 修改目录的解释信息。 |
祁彩云 |
目的和范围
本制度就公司软件项目的文件管理和目录结构做出规定和建议。
- 对于采用 MSF 作为开发流程的项目来说，本制度为强制性的。
- 对于其它项目，应尽可能参照本制度执行。
用词说明
为了便于在执行本标准条文时区别对待，对要求严格程度不同的用词说明如下：
1） 表示很严格，非这样做不可的用词：
正面词采用“必须”，反面词采用“严禁”；
2） 表示严格，在正常情况下均应这样做的用词：
正面词采用“应”，反面词采用“不应”或“不得”；
3） 表示允许稍有选择，在条件许可时首先应这样做的用词：
正面词采用“宜”，反面词采用“不宜”；
4） 表示有选择，在一定条件下可以这样做的用词，采用“可”。
条文中指明应按其他有关标准、规范执行的写法为：“应符合……规定”或“应按……执行”。
术语和定义
为了确保对术语的一致性理解，此处定义本文档用到的术语：
- MSF： Microsoft Solution Framework 的缩写，是微软产品研发的方法论，2022 年起公司借鉴其方法论开展研发管理工作。
- 仓库： repository，研发过程中的文档、代码、测试用例等文档都必须放到仓库中。
- 资产类文档：研发过程中的文档、代码、测试用例等文档都称为资产类文档。
参考文献
主要参考的 git 代码库：
- C# language：这个库里没有代码，记录了 C# 语言规范、提案、会议纪要。
一般性规定
应尽早建立并使用仓库管理资产。对于 MSF 项目，早在展望阶段，就应该建立并使用仓库。
一个 MSF 项目应只有一个仓库。如果需要增设更多仓库，必须向软件部提出申请。
仓库必须采用 git 作为版本管理工具。
资产类文档必须存放到仓库中。
注：如果本规范不合适你的项目，请向软件部提出申请。经过软件部书面答复后，方可变更。
目录结构
仓库必须符合本节要求的目录结构。
原则：
- 宜采用浅的目录结构，或者称为扁平的目录结构。
- 可选文件和目录，应等到需要的时候再去建立。
- 目录和文件名应尽可能采用英文。
请注意，目录和文件名的大小写必须符合规定。这是因为考虑到 linux 平台的可移植性。
git 服务器端的目录和文件结构：
<project-name>/ ; project root dir
+-- doc/
+-- srs/
+-- design/
+-- manual
+-- pm/
+-- risk.md
+-- roles.md
+-- stakeholder.md
+-- src/
+-- test/
+-- .editorconfig ; or `.clang-format`
+-- .gitattributes
+-- .gitignore
+-- README.md
+-- <project-name>.sln
解释
- <project-name>/ - 项目根目录。
- doc/ - 资产类型的文件目录，包括 规格说明书（srs）、设计方案（design）、用户相关文档（manual）。
- doc/srs/ - SRS 文件
- doc/design/ - 设计方案文件
- pm/ - 项目文件目录，主要是过程文档，包括项目风险文件、利益相关人和项目结构文件、会议纪要等。
- src/ - 源代代码文件夹。
- test/ - 测试用例文件夹。
- .gitignore - 忽略文件配置清单。将会影响到如
git add和git clean这样的命令。可以用gitignore.io生成一个干净有用的 .gitignore 文件。 - .gitattributes - 用来定义文件的属性（如：更改文件在差异中的外观）。
- .editorconfig|.clang-format - 代码格式化文件。
- README.md - 项目简介文件。很重要！
- <project-name>.sln - VS 解决方案文件，或者类似作用的 build 脚本。也许有多个类似文件。
如果有些文档很难区分是资产或过程类文件，边界比较模糊的情况，如果当前比较重要，可以根据需要放到doc、根目录甚至在 Readme 中体现。
可选目录
<project-name>/
+-- sample/
+-- tool/
- sample/ - 提供样例代码，以便新人快速入门，一般小型的库有这个目录。
- tool/ - 工具类文件夹，一般包括自动构建、持续集成之类的任务脚本等，大多是批处理文件。
README.md 文件
这是一个非常重要的文件。其存在的价值在于，让新加入项目的同事，能够通过阅读本文件对整个项目有个概况性了解。是否很好地实现了这个价值，是判断 README.md 文件的合格与否的关键标准。
依据 MSF 在展望历程的关键输出文档远景/范围文件，其内容如下：
远景/范围文件
- 问题陈述
- 远景/使命
- 高层需求，SMART原则
- 用户特征
- 设计策略：架构&技术
- 定义验收标准
可以发现这些内容对于概括性了解整个项目很重要，因此这些内容就应作为 README.md 的主体而存在。README.md 的主体结构如下：
# <project-name>
## 概述
## 远景/使命
## 高层需求
## 用户分类
## 设计策略
## 验收标准
可以再加上其它内容，比如：
- 如何编译
- 版本说明
项目文件目录
项目文件目录为 pm。用于存放 MSF 各个历程的项目管理相关文件。包括：
stakeholder.md利益关系人文件（干系人）roles.mdMSF 团队角色文件risk.md风险评估文件
SRS 文件
原则
SRS文档存放在 /doc/srs/ 目录下，采用源代码方式管理。
SRS不是一个大文件，而是按照SRS标准中规定的结构拆分为三个章节，【引言】和【总体描述】分别为一个或多个文件，【详细描述】部分按照功能分类后独立成更小的文件，然后经过
docfx工具拼起来。SRS必须使用markdown(.md)格式，不得采用WORD(.doc), EXCEL(.xls)等格式。
SRS的图片等资源文件，须放在文档同级目录的./images/或./media/目录下， 也可统一存放在 /doc/srs/res/ 目录下。
在markdown格式的文件里，不应编制大型表格。原因是这种大型表格编写和维护困难，并且难以进行版本比对。
SRS编写细节请参照相关标准及编写指导书，具体在【附录】章节，特别注意，第三章有多种写法，其具体格式不做要求，关键描述用户可以感知到的集合及非功能性规格。
目录
SRS 是多个子文件拼接起来的大文档，各个子文件的目录结构大致如下，该部分不做强制要求，符合目录结构尽量扁平的原则即可：
+-- srs/
+--引言.md
+--总体描述.md
+--XXX功能或功能集合/
+--XXX功能或子功能.md
解释
引言 - 可以是一个或拆分为多个.md文件。
总体描述 - 可以是一个或拆分为多个.md文件。
XXX功能或功能集合 - 详细描述部分，功能集或功能分类文件夹，不是必须，根据功能粒度自行选择创建，功能分级一般不超过三级目录。
XXX功能或子功能 - srs的功能集或分类下的功能或子功能文件，通过该.md文档详细描述该功能。
附录
1 ） 微盘路径：软件部学习资料共享->需求分析参考书
- SRS 标准 -《9385——2008 计算机软件需求规格说明书规范》
2 ） 软件项目目录与文件管理规范
github 发布链接：https://weihong-phoenix.github.io/doc/研发管理制度规范/软件项目目录与文件管理规范-R1.html
3 ） 文档编写指南&规范
文档编写规范：github 发布链接：https://weihong-phoenix.github.io/doc/研发文档编写指南/研发文档编写规范.html
SRS-编写指导（前面两大章节）
README-编写指导（ToDo）
roles-编写指导（ToDo）
stakeholder-编写指导（ToDo）
risk-编写指导（ToDo）