开发流程

这个项目采用轻量的 trunk-based development。main 应始终处于可构建、可测试、可以部署到测试集群的状态。

分支与提交

日常改动从最新 main 创建短生命周期分支：

feature/<主题>   新能力
fix/<主题>       缺陷修复
refactor/<主题>  不改变行为的重构
docs/<主题>      文档
chore/<主题>     工具、依赖和 CI

提交信息使用 <类型>: <中文说明>，例如：

feat: 添加 PostgreSQLTenant 默认值校验
fix: 保留删除中的数据库租户
test: 覆盖 OpenBao 写入失败后的重试

允许的常用类型为 feat、fix、refactor、test、docs、chore 和 ci。一个提交只表达一个可理解的变更；禁止提交真实数据库凭据、OpenBao Token、 kubeconfig 或本地生成的二进制。

开发循环

从最新 main 创建分支。
先新增或修改规格，覆盖范围、非目标、外部行为、校验、失败语义、安全边界和验收标准；获得人工批准前不得实现行为。
从已批准验收标准派生失败测试，再实现最小纵向切片。若实现暴露规格歧义，返回规格阶段重新审批。
修改 API type 或 Kubebuilder marker 后运行：
```
make manifests generate
```

提交前运行：

make test
make lint
git diff --exit-code

达到一个小而完整、可独立 review 的边界时，先请求批准再创建 commit；一个 PR 可以包含多个这样的 commit。
推送分支后，在创建 PR 前再次请求批准。PR 说明应包含规格链接、动机、行为变化、验证方式，以及对 PostgreSQL、OpenBao、ESO 和凭据的风险。
CI 通过后按仓库策略合并，删除已合并分支。

make test-e2e 会创建并删除名为 postgresql-tenant-operator-test-e2e 的 Kind 集群，只能在隔离环境运行，不能指向 homelab 日常集群。

CI 层次

Gitea Actions 直接使用 .github/workflows 中兼容 GitHub Actions 语法的工作流：

Tests：运行生成、格式化、vet、envtest，并检查生成文件和 go.mod/go.sum 没有未提交漂移。
Lint：校验 golangci-lint 配置并运行静态检查。
E2E Tests：在一次性 Kind 集群中安装 CRD 和 controller，执行端到端验证。

三个工作流都在 PR 上运行，并在合并进入 main 后再次运行；E2E 也支持手动触发。所有 job 固定使用集群内的 self-hosted Docker runner。E2E runner 必须能够访问 Docker daemon，供 Kind 创建临时节点容器。建议在 Gitea 中保护 main，要求三个检查通过并禁止 force push。

Controller 约定

reconcile 必须幂等，以 PostgreSQL catalog 和 OpenBao 为事实来源。
status 只记录观察结果，不保存明文秘密，也不作为外部资源的事实来源。
外部调用必须有超时、可重试，并区分永久错误与暂时错误。
日志、Event、Condition message 和测试输出不得包含密码或管理凭据。
默认删除策略是 Retain；任何实际销毁路径都必须有 finalizer 和独立测试。
controller 测试优先使用 fake PostgreSQL/OpenBao/ESO client；API 交互使用 envtest； PostgreSQL/OpenBao adapter 使用 Docker 集成测试，完整网络和 ESO 投射留给 Kind E2E。

API 变更

v1alpha1 允许快速调整，但每次 schema 变更仍需同步修改：

Go API types 和校验 marker；
生成的 CRD 与 RBAC；
config/samples；
架构或用户文档；
conversion/defaulting 需求评估；
覆盖新旧行为的测试。

不要手工编辑 PROJECT、zz_generated.*.go、config/crd/bases 或生成的 RBAC；使用 Kubebuilder、make manifests 和 make generate 更新它们。

3.8 KiB Raw Blame History Unescape Escape