101 lines
4.1 KiB
Markdown
101 lines
4.1 KiB
Markdown
# 开发流程
|
||
|
||
这个项目采用轻量的 trunk-based development。`main` 应始终处于可构建、可测试、
|
||
可以部署到测试集群的状态。
|
||
|
||
## 分支与提交
|
||
|
||
日常改动从最新 `main` 创建短生命周期分支：
|
||
|
||
```text
|
||
feature/<主题> 新能力
|
||
fix/<主题> 缺陷修复
|
||
refactor/<主题> 不改变行为的重构
|
||
docs/<主题> 文档
|
||
chore/<主题> 工具、依赖和 CI
|
||
```
|
||
|
||
提交信息使用 `<类型>: <中文说明>`，例如：
|
||
|
||
```text
|
||
feat: 添加 PostgreSQLTenant 默认值校验
|
||
fix: 保留删除中的数据库租户
|
||
test: 覆盖 OpenBao 写入失败后的重试
|
||
```
|
||
|
||
允许的常用类型为 `feat`、`fix`、`refactor`、`test`、`docs`、`chore` 和
|
||
`ci`。一个提交只表达一个可理解的变更；禁止提交真实数据库凭据、OpenBao Token、
|
||
kubeconfig 或本地生成的二进制。
|
||
|
||
## 开发循环
|
||
|
||
1. 从最新 `main` 创建分支。
|
||
2. 先新增或修改规格，覆盖范围、非目标、外部行为、校验、失败语义、安全边界和验收
|
||
标准；获得人工批准前不得实现行为。
|
||
3. 从已批准验收标准派生失败测试，再实现最小纵向切片。若实现暴露规格歧义，返回
|
||
规格阶段重新审批。
|
||
4. 修改 API type 或 Kubebuilder marker 后运行：
|
||
|
||
```sh
|
||
make manifests generate
|
||
```
|
||
|
||
5. 提交前运行：
|
||
|
||
```sh
|
||
make lint
|
||
git diff --check
|
||
```
|
||
|
||
Agent 日常本地迭代不运行耗时的完整 `make test` 或 Kind E2E；生成一致性、Tests 和 E2E
|
||
由获准创建 PR 后的 self-hosted Gitea Actions 执行。只有排查特定失败或人工明确要求时
|
||
才运行针对性的本地测试。
|
||
|
||
6. 达到一个小而完整、可独立 review 的边界时，先请求批准再创建 commit；一个 PR
|
||
可以包含多个这样的 commit。
|
||
7. 推送分支后，在创建 PR 前再次请求批准。PR 说明应包含规格链接、动机、行为变化、
|
||
验证方式，以及对 PostgreSQL、OpenBao、ESO 和凭据的风险。
|
||
8. CI 通过后按仓库策略合并，删除已合并分支。
|
||
|
||
`make test-e2e` 会创建并删除名为
|
||
`postgresql-tenant-operator-test-e2e` 的 Kind 集群，只能在隔离环境运行，不能指向
|
||
homelab 日常集群。
|
||
|
||
## CI 层次
|
||
|
||
Gitea Actions 直接使用 `.github/workflows` 中兼容 GitHub Actions 语法的工作流：
|
||
|
||
- `Tests`：运行生成、格式化、vet、envtest、一次性 Docker adapter integration tests，
|
||
并检查生成文件和 `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` 更新它们。
|