软件项目目录与文件管理规范
目的和范围
本规范就公司软件项目的文件管理和目录结构做出规定和建议。
- 对于采用 MSF 作为开发流程的项目来说，本规范为强制性的。
- 对于其它项目，应尽可能参照本规范执行。
用词说明
为了便于在执行本标准条文时区别对待，对要求严格程度不同的用词说明如下：
1） 表示很严格，非这样做不可的用词：
正面词采用 “必须”，反面词采用 “严禁”；
2） 表示严格，在正常情况下均应这样做的用词：
正面词采用 “应”，反面词采用 “不应” 或 “不得”；
3） 表示允许稍有选择，在条件许可时首先应这样做的用词：
正面词采用 “宜”，反面词采用 “不宜”；
4） 表示有选择，在一定条件下可以这样做的用词，采用 “可”。
条文中指明应按其他有关标准、规范执行的写法为：“应符合……规定” 或 “应按……执行”。
术语和定义
为了确保对术语的一致性理解，此处定义本文档用到的术语：
- SRS：Software Requirement Specification 的缩写，软件需求规格说明书。
- MSF： Microsoft Solution Framework 的缩写，是微软产品研发的方法论，2022 年起公司借鉴其方法论开展研发管理工作。
- 仓库： repository，研发过程中的文档、代码、测试用例等文档都必须放到仓库中。
- 资产类文档：研发过程中的文档、代码、测试用例等文档都称为资产类文档。
参考文献
主要参考的 GIT 代码库：
- C# language：这个库里没有代码，记录了 C# 语言规范、提案、会议纪要。
一般性规定
应尽早建立并使用仓库管理资产。对于 MSF 项目，早在展望阶段，就应该建立并使用仓库。
一个 MSF 项目应只有一个仓库。如果需要增设更多仓库，必须向软件部提出申请。
仓库必须采用 GIT 作为版本管理工具。
资产类文档必须存放到仓库中。
Note
如果本规范不合适你的项目，请向软件部提出申请。经过软件部书面答复后，方可变更。
目录结构
仓库必须符合本节要求的目录结构。
原则：
- 宜采用浅的目录结构，或者称为扁平的目录结构。
- 可选文件和目录，应等到需要的时候再去建立。
- 目录和文件名应尽可能采用英文。
- 请注意，目录和文件名的大小写必须符合规定。这是因为考虑到 linux 平台的可移植性。
- 目录和文件名都不允许带版本标识。
- 仓库下不存储已作废可删除的文件。
- 每个仓库下都必须有 README.md 文件，除 README.md 文档外，文档都存储在 doc/ 目录下。
doc/ 目录下只有文档，不允许有可执行文件。
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 脚本。也许有多个类似文件。
Note
如果有些文档很难区分是资产或过程类文件，边界比较模糊的情况，如果当前比较重要，可以根据需要放到 doc/ 目录，可在 README.md 中说明。
可选目录
原则：
- 样例代码或 exe 之类的应用程序文件，尽量放置在 sample 或 tool 目录下。
<project-name>/
+-- sample/
+-- tool/
- sample/ - 提供样例代码，以便新人快速入门，一般小型的库有这个目录。
- tool/ - 工具类文件夹，一般包括自动构建、持续集成之类的任务脚本等，大多是批处理文件。
README.md 文件
这是一个非常重要的文件。其存在的价值在于，让新加入项目的同事，能够通过阅读本文件对整个项目有个概况性了解。是否很好地实现了这个价值，是判断 README.md 文件的合格与否的关键标准。
依据 MSF 在展望历程的关键输出文档 远景/范围文件，其内容如下：
- 问题陈述
- 远景/使命
- 高层需求，SMART原则
- 用户特征
- 设计策略：架构&技术
- 定义验收标准
可以发现这些内容对于概括性了解整个项目很重要，因此这些内容就应作为 README.md 的主体而存在。README.md 的主体结构如下：
# <project-name>
## 概述
## 远景/使命
## 高层需求
## 用户分类
## 设计策略
## 验收标准
可以再加上其它内容，比如：
- 如何编译
- 版本说明
项目文件目录
项目文件目录为 pm/，和 doc/ 目录同级。用于存放 MSF 各个历程的项目管理相关文件。包括：
stakeholder.md利益关系人文件（干系人）roles.mdMSF 团队角色文件risk.md风险评估文件
SRS 文件
SRS 文件目录为 doc/srs/。用于存放需求规格说明书。
原则：
SRS 文档必须存放在 doc/srs/ 目录下，采用源代码方式管理。
SRS 不是一个大文件，而是按照 SRS 标准中规定的结构拆分为三个章节，引言 和 总体描述 章节分别为一个或多个文件， 详细描述 部分按照功能分类后独立成更小的文件，然后经过
DOCFX工具拼起来。SRS 必须使用 Markdown(.md) 格式，不得采用 WORD(.doc), EXCEL(.xls) 等格式。
SRS 的图片等资源文件，须放在文档同级目录的 media/ 目录下， 也可统一存放在 doc/srs/res/ 目录下。
在 Markdown 格式的文件里，不应编制大型表格。原因是这种大型表格编写和维护困难，并且难以进行版本比对。
SRS 编写细节请参照相关标准及编写指导书，具体在 附录 章节，特别注意，第三章有多种写法，其具体格式不做要求，关键描述用户可以感知到的集合及非功能性规格。
目录：
SRS 是多个子文件拼接起来的大文档，各个子文件的目录结构大致如下，该部分不做强制要求，符合目录结构 尽量扁平 的原则即可：
+-- srs/
+--引言.md
+--总体描述.md
+--XXX功能或功能集合/
+--XXX功能或子功能.md
解释：
引言 - 可以是一个或拆分为多个.md文件。
总体描述 - 可以是一个或拆分为多个.md文件。
XXX功能或功能集合 - 详细描述部分，功能集或功能分类文件夹，不是必须，根据功能粒度自行选择创建，功能分级一般不超过三级目录。
XXX功能或子功能 - srs的功能集或分类下的功能或子功能文件，通过该.md文档详细描述该功能。