Repo Hygiene

本文件定义 Servify 仓库中源码、生成物、运行时文件的边界，避免工作区被临时文件、二进制和缓存污染。

必须提交的内容

  • 所有源码、配置模板、文档、测试代码
  • 通过 generated-assets.manifest 明确声明的生成物
  • 已被仓库设计为“发布面的一部分”的产物，例如 demo SDK 提交产物和 API 文档产物

不应提交的内容

  • 本地构建出的二进制，例如根目录 server、server.exe
  • 运行时上传目录、测试执行时的临时上传文件
  • 本地缓存、日志、覆盖率、临时数据库
  • 可由包管理器或构建命令稳定重建的普通构建缓存

当前明确边界

  • generated-assets.manifest
    • 这里列出的文件必须存在，并且必须被 Git 跟踪
  • uploads/、apps/server/uploads/、internal/handlers/uploads/
    • 视为运行时或测试产物，不应进入版本控制
  • ./.runtime/
    • 作为本地运行时目录根，承载上传文件、临时运行输出等非源码内容
  • /server、/server.exe
    • 视为本地构建二进制，不应进入版本控制

测试约定

  • 上传类测试优先使用 t.TempDir() 或系统临时目录
  • 如果测试确实依赖静态样本，应放入明确的 fixture / testdata 目录，而不是运行时上传目录
  • 测试结束后应清理自己创建的临时文件

命名约定

  • testdata/
    • 可提交、稳定、可复用的测试样本
  • fixtures/
    • 需要明确语义分组的跨测试样本集合
  • generated/
    • 明确属于生成物且通常需要额外生成入口说明的内容
  • .runtime/
    • 本地运行时输出，不提交

生成物约定

  • 需要提交的生成物必须有稳定生成入口，并且能在 CI 中校验
  • 新增生成物时，要同时更新：
    • 生成脚本或命令入口
    • generated-assets.manifest 或等价校验机制
    • 对应文档说明
  • 当前受控生成物说明见 docs/generated-assets.md

新增目录时的默认判断

  • 如果目录内容是源码、文档、fixtures、契约文件，通常应该提交
  • 如果目录内容是运行时输出、缓存、编译结果、下载内容，通常不应提交
  • 如果目录内容介于两者之间，必须先明确“是否可重建”和“CI 是否要校验”

新增目录默认 ignore 约定

  • 新增运行时目录：
    • 默认放入 .runtime/ 或子应用自己的 runtime 目录
    • 默认加入 .gitignore
  • 新增缓存目录：
    • 默认加入 .gitignore
    • 名称优先使用 .cache/、工具默认缓存目录或子项目本地缓存目录
  • 新增构建输出目录：
    • 默认不提交
    • 只有被明确设计为受控生成物时，才允许提交并进入治理流程
  • 新增测试样本目录：
    • 优先使用 testdata/ 或 fixtures/
    • 默认允许提交
  • 新增生成物目录：
    • 如果需要提交，补文档、生成命令、CI 校验
    • 如果不需要提交，加入 .gitignore

根目录治理

  • 根目录优先放入口级内容，例如：
    • 顶层文档
    • 顶层配置样例
    • 顶层构建入口
    • 跨应用共享脚本与清单
  • 应用内部样本、运行时文件、模块私有文档应尽量回到各自子目录
  • 新增根目录文件前，先判断是否属于：
    • 全仓库入口
    • 跨目录共享规则
    • 发布或构建主链路
  • 如果不属于以上三类，通常不应放在根目录