swe-devops-standards

地理空间软件工程与 DevOps 标准

目的：作为地理空间工作一部分生成的代码，应能在用户的真实环境中运行，并达到同行级别的工程质量。仅当代码或仓库产物属于任务范围时，才应用这些规则。

1. 环境现实（最常见的错误来源）

• 默认优先编写脚本：除非用户明确在笔记本环境中，否则不要使用 %matplotlib inline、!pip install 或 display()。每个文件都应能通过终端中的 python script.py 运行，并放在 if __name__ == "__main__": 代码块后。（可以额外添加 # %% 之类的单元格标记，但脚本也必须能够在没有这些标记的情况下运行。）
• 跨平台路径：始终使用 pathlib.Path；切勿拼接字符串或硬编码 / 或 \\。提供 Shell 命令前，先询问或检测用户的操作系统；Windows 使用 CMD/PowerShell 语法，其他系统使用 POSIX 语法——不要混用（export 与 set、venv/bin/activate 与 venv\Scripts\activate）。
• 编码：打开每个文本文件时都显式指定 encoding="utf-8"——Windows 仍默认使用旧代码页，非 ASCII 内容可能会在不报错的情况下损坏。
• 现代 Python（3.11+）：使用 X | None 联合类型、type 别名，以及能让代码更清晰的结构化模式匹配；如果某项特性有最低版本要求，请注明。

2. 默认代码质量要求

即使用户未提出要求，也适用于每个生成的函数/模块：

def compute_share(values: list[float], total: float) -> list[float]:
    """Return each value's share of the total.

    Args:
        values: Values to compute shares for.
        total: Denominator; must be non-zero.

    Returns:
        Shares in the same order as values.

    Raises:
        ValueError: If total is zero.
    """
    if total == 0:
        raise ValueError("total must be non-zero — share is undefined.")
    return [v / total for v in values]

• 每个函数签名都要有类型提示；复杂类型使用 dataclass/TypeAlias。
• 使用 Google 风格的文档字符串；简单函数用单行说明即可。
• 绝不使用裸 except:；捕获特定异常，并进行处理或使用 raise ... from e 重新抛出。静默的 pass 会让调试工作多花一周。
• 使用 logging 而非 print（设置级别并进行格式化），面向用户的 CLI 输出除外。
• 在相关之处说明算法复杂度（“这是 O(n log n)，n>10⁶ 时仍安全”）——尤其是嵌套循环和 pandas apply。
• 将魔法数字改为模块级命名常量。

3. 测试与验证

• 对每个包含实际逻辑的函数，至少提供一个 pytest 测试框架：

# test_compute.py — run: python -m pytest -q
import pytest
from compute import compute_share

def test_basic() -> None:
    assert compute_share([1, 1], 2) == [0.5, 0.5]

def test_zero_total_raises() -> None:
    with pytest.raises(ValueError):
        compute_share([1.0], 0)

• 数值代码：测试边界情况——空输入、NaN、负数、单个元素。
• 有执行环境时，亲自运行生成的代码；否则明确标注“未执行”——不要默默假设代码可运行。

4. 依赖项与可复现性

• 新项目 → 虚拟环境 + 固定版本的 requirements.txt（package==version）；切勿“安装最新版”。
• 为随机过程设置种子，并将种子写入配置（详情见 ml-experiment-standards）。
• 在相关之处说明环境差异带来的风险（BLAS、CUDA、区域设置）。

5. Git 实践

• Conventional Commits：feat(scope): ...、fix: ...、refactor: ...；提交说明解释为什么——差异已经展示了做了什么。
• 按有意义的单元提交；提醒用户避免一次提交 500 行内容。
• 默认 .gitignore：venv/、__pycache__/、*.pyc、大型数据文件（建议使用 DVC/LFS）、IDE 文件夹。

6. 自动化 / DevOps

• CI：使用精简的 GitHub Actions 运行测试 + lint（ruff）；如果任务也必须在 Windows 上运行，请说明操作系统运行器的差异。
• Docker：从 python:3.12-slim 开始，在体积/缓存需求要求更复杂的方案之前，采用简单的单阶段构建；说明镜像大小和构建缓存的影响。
• 监控：任何长期运行的服务/管道至少提供三种信号：结构化日志、故障告警、基本指标（时长、数量）。ML 服务还应添加漂移检查（见 ml-experiment-standards）。
• 定时任务：根据用户的平台选择方案——POSIX 上使用 cron，Windows 上使用任务计划程序（schtasks）。

7. 代码审查模式

按以下顺序审查并按严重程度报告发现的问题：正确性（边界情况、静默失败）→ 安全性（注入、机密信息、路径遍历）→ 性能（N+1、不必要的复制、O(n²)）→ 可读性。每项发现都必须附上以代码形式给出的建议修复方案——不能只说“这不好”而不提供其他内容。

执行约定

• 工作流： 明确地理空间代码的约定；复现环境；检查正确性和数据不变量；实施最小且安全的更改；测试；打包；记录运维和回滚说明。
• 决策规则： 将此技能用于地理空间软件和流水线交付，而非通用的非空间编码；根据实际部署风险调整 CI、容器和可观测性。
• 验证流程： 运行针对性测试和回归测试；在已配置的情况下执行 lint 和类型检查；检验 CRS、无数据值和几何边缘情况；验证能否干净安装；审查 CI 产物。
• 故障模式： 若存在静默数据丢失、非确定性、可变的隐藏状态、未锁定的关键依赖、机密信息、平台假设、缺少回滚方案或未处理的空间边缘情况，则阻止发布。
• 交付物： 经审查的代码、测试、可复现环境和锁定数据、CI 配置、运维说明、按风险排序的发现、可观测性计划和回滚说明。
• 来源时效性： 应先查阅权威来源注册表，再采用有关打包、CI、测试或供应链的指导。