📚 课程目录第4章源码仓库结构规范

4. 源码仓库结构规范：目录命名规则、文件组织方式、README模板、CHANGELOG规范

Collector管道移植适配项目的源码仓库是平台工程自助目录的核心交付物。一个结构清晰、命名一致的仓库，能够显著降低新成员的上手成本，并确保CI/CD流水线能够自动识别关键文件。本章定义仓库的目录命名规则、文件组织方式、README模板以及CHANGELOG规范。

4.1 目录命名规则

所有目录名称必须遵循以下规则，以保证跨平台（Linux/Windows/macOS）的兼容性和可读性：

小写字母：禁止使用大写字母，例如使用 config 而非 Config。
连字符分隔：多单词目录使用连字符（-）连接，例如 collector-plugins。
禁止特殊字符：不允许使用空格、下划线（_）、点号（.）作为目录名起始字符。
语义化：目录名必须反映其内容职责，避免使用 tmp、misc 等模糊命名。

  命名速查表：scripts（脚本）、templates（模板）、patches（补丁）、tests（测试）、docs（文档）。

4.2 文件组织方式

仓库根目录下的文件组织采用“分层职责”模型，将配置、源码、文档和CI/CD定义分离。标准结构如下：

collector-adapter-repo/
├── .github/
│   └── workflows/          # GitHub Actions 流水线定义
├── config/                 # 管道移植适配的配置文件
│   ├── collector.yaml      # 主配置
│   └── pipeline-mapping.json
├── scripts/                # 辅助脚本（移植、验证、清理）
│   ├── migrate.sh
│   └── validate.sh
├── src/                    # 核心源码或补丁
│   ├── patches/            # 针对目标平台的补丁文件
│   └── plugins/            # 自定义Collector插件
├── tests/                  # 单元测试与集成测试
│   ├── unit/
│   └── integration/
├── docs/                   # 项目文档
│   ├── architecture.md
│   └── troubleshooting.md
├── .gitignore
├── README.md               # 项目入口文档
├── CHANGELOG.md            # 版本变更记录
└── LICENSE

最佳实践：config/ 目录下的配置文件应使用版本号或环境后缀（如 .prod.yaml）进行区分，避免覆盖风险。

4.3 README模板

每个仓库必须包含 README.md，并遵循以下标准模板结构。模板确保新用户能够在5分钟内完成环境搭建和首次运行。

章节	内容要求	示例
项目标题	仓库名称 + 一句话描述	`# collector-adapter-repo` Collector管道移植适配标准仓库
快速开始	前置依赖、安装命令、运行示例	`pip install -r requirements.txt`
目录结构	使用树形图展示关键目录	如上节所示
配置说明	环境变量、配置文件路径、参数解释	`export COLLECTOR_CONFIG=./config/collector.yaml`
贡献指南	分支策略、PR流程、代码风格	参考 `CONTRIBUTING.md`
许可证	明确开源协议类型	Apache 2.0

注意：README中禁止包含过时的截图或失效的链接。每次版本发布前，必须验证所有命令和路径的有效性。

4.4 CHANGELOG规范

CHANGELOG遵循 Keep a Changelog 标准，并结合语义化版本（SemVer）进行管理。每次发布必须更新该文件。

版本号格式：MAJOR.MINOR.PATCH，例如 v1.2.3。

Added：新增功能或文件。
Changed：现有功能或配置的变更。
Deprecated：即将废弃的功能。
Removed：已移除的功能。
Fixed：Bug修复。
Security：安全漏洞修复。

# Changelog

## [v1.2.0] - 2025-03-15

### Added
- 新增对 ARM64 架构的 Collector 移植支持。
- 新增 `config/pipeline-mapping.json` 配置文件模板。

### Changed
- 升级基础镜像至 Alpine 3.19，减少安全漏洞。
- 优化 `scripts/migrate.sh` 的执行效率，减少 30% 的迁移时间。

### Fixed
- 修复在 macOS 环境下路径分隔符导致的脚本执行失败问题。

## [v1.1.0] - 2025-02-20

### Added
- 首次发布，支持 x86_64 平台的管道移植适配。

4.5 仓库结构关系图

下图展示了仓库各目录之间的数据流与依赖关系，帮助理解文件组织方式背后的设计逻辑。

4.6 文件组织避坑清单

在实际交付中，常见以下组织错误，应通过代码审查和自动化检查加以规避：

配置文件散落：将 .yaml 或 .json 放在根目录而非 config/ 下，导致CI/CD无法统一挂载。
脚本与源码混放：在 src/ 中直接放置 .sh 脚本，应统一归入 scripts/。
文档缺失：缺少 CHANGELOG.md 或 README.md 中未包含快速开始命令。
忽略 .gitignore：未排除 __pycache__、.env、*.log 等文件，导致仓库体积膨胀。

  自动化检查建议：在 CI 流水线中加入 repo-structure-validator 步骤，检查目录是否存在、README 是否包含必填章节、CHANGELOG 版本号是否与 Git Tag 一致。