rs-toolkit/CONVENTIONS.md

Harmon 代码协定

适用于 git.rsharmon.cn/Harmon 下的所有仓库（GitHub HarmonRS 为镜像）。新代码必须遵守，旧代码在修改时逐步对齐。

1. 仓库命名

• 全小写，短横线连接：领域-数据源-功能，如 sar-lt1-dinsar、sar-gf3-l1a2l2、s1-orbit-downloader。
• 常用前缀：sar（雷达通用）、lt1（陆探1号）、gf3（高分3号）、s1（Sentinel-1）、opt（光学）。
• 禁止下划线、大写、-v2/-new/-final 之类的版本后缀（版本靠 tag）。
• 主力项目（系统/服务）独立成仓库；小工具、脚本统一放进 rs-toolkit。

2. rs-toolkit 目录结构

rs-toolkit/
  idl/<工具名>/       # IDL/ENVI 脚本
  python/<工具名>/    # 每个工具是独立的 Python 包
  go/<工具名>/        # 如有
  README.md           # 工具索引：一行说明 + 安装/运行方式
  CONVENTIONS.md

• 工具目录名同样遵守第 1 条命名规则。
• 工具之间不互相 import；共用代码再考虑抽成 python/rs-common/。
• 新增工具时同步更新根 README 索引。

3. 分支与提交

• 默认分支 main，始终保持可用；功能在 feat/xxx、fix/xxx 分支上开发，通过 PR 合并。
• 提交信息采用 Conventional Commits：<type>(<scope>): <说明>
  • type：feat fix refactor docs test chore ci perf
  • scope：rs-toolkit 中写工具名，如 fix(sar-gf3-l1a2l2): 跳过损坏的压缩包
• 一个提交只做一件事；不提交生成物、数据、密钥。
• 发布打 tag：主项目 vX.Y.Z；toolkit 内工具 <工具名>-vX.Y.Z。

4. Python

• 一律 pyproject.toml + src/ 布局：src/<包名>/，包名为目录名的下划线形式。
• 声明 requires-python、依赖下限，命令行入口写在 [project.scripts]。
• 安装方式（无需拷脚本）： pip install "git+https://git.rsharmon.cn/Harmon/rs-toolkit.git#subdirectory=python/<工具名>"
• 代码用 ruff 检查与格式化；测试放 tests/，用 pytest。
• 路径、账号等配置不写死在代码里，走命令行参数/配置文件/环境变量。

5. IDL / ENVI

• 文件名小写下划线（IDL 惯例），一个 .pro 一个主过程，过程名与文件名一致。
• 文件头注释写明：用途、输入输出、依赖的 ENVI/SARscape 版本、作者与日期。
• 输入输出路径作为参数传入，不写死；批处理入口统一命名 batch_*.pro。
• .sav 等编译产物如必须入库，标记为 binary（.gitattributes）。

6. README 要求

每个仓库/工具目录必须有 README，至少包含：

1. 一句话说明做什么；2. 环境与依赖；3. 安装；4. 最小运行示例；5. 输入/输出说明；6. 已知限制。

7. CI

• 每个仓库在 .gitea/workflows/ 下配置 CI，PR 和推送 main 时触发。
• Python：ruff + 编译检查 + pytest（有测试时）；Rust：cargo fmt --check、cargo clippy -D warnings、cargo test；Go：go vet、go test。
• main 开分支保护：CI 通过后才能合并。AI 生成的代码同样必须过 CI。

8. 其他

• 文本统一 UTF-8、LF（Windows .cmd/.bat 除外）。
• 大于 10MB 的二进制/数据不入库，放 release 或 NAS。