docs: add design spec for issue 18 CI checks

Record the approved design to add go vet and pinned staticcheck jobs to PR CI with minimal workflow changes.
2026-04-28 07:25:52 +07:00
parent 094bd35de4
commit c112ac37c9
1 changed files with 76 additions and 0 deletions
@@ -0,0 +1,76 @@
+# Design: Issue #18 — Add `go vet` and `staticcheck` to CI
+
+## Context
+Issue #18 requires expanding PR CI validation for this Go repository beyond existing `gofmt` and `go test` checks.
+
+Current state:
+- CI is defined in `.gitea/workflows/ci.yml`.
+- Existing jobs: `fmt` (`gofmt -l .`) and `test` (`go test ./...`).
+- No `go vet` or `staticcheck` step exists.
+
+## Goal
+Add practical baseline static analysis to pull request CI by:
+- Running `go vet ./...`.
+- Running `staticcheck ./...`.
+- Pinning `staticcheck` version in CI for deterministic behavior.
+
+## Non-goals
+- Adding `golangci-lint`.
+- Refactoring application code unrelated to CI wiring.
+- Changing workflow triggers.
+
+## Approved approach
+Use separate CI jobs for `vet` and `staticcheck` while keeping existing `fmt` and `test` jobs unchanged.
+
+### Why this approach
+- Keeps changes surgical and easy to review.
+- Makes failures explicit per check (better debugging signal than a combined lint step).
+- Preserves current CI behavior while extending validation coverage.
+
+## Implementation design
+Modify `.gitea/workflows/ci.yml` only.
+
+### Job: `vet`
+- `runs-on: linux`
+- Steps:
+  1. `actions/checkout@v4`
+  2. `actions/setup-go@v5` with `go-version-file: go.mod`
+  3. `run: go vet ./...`
+
+### Job: `staticcheck`
+- `runs-on: linux`
+- Steps:
+  1. `actions/checkout@v4`
+  2. `actions/setup-go@v5` with `go-version-file: go.mod`
+  3. Install pinned staticcheck version:
+     - `go install honnef.co/go/tools/cmd/staticcheck@2025.1.1`
+  4. Run staticcheck:
+     - `$(go env GOPATH)/bin/staticcheck ./...`
+
+## Failure behavior
+- CI must fail if `go vet ./...` exits non-zero.
+- CI must fail if `staticcheck ./...` exits non-zero.
+- Existing `fmt` and `test` failure behavior remains unchanged.
+
+## Verification plan
+Local verification before PR creation:
+- `gofmt -l .`
+- `go test ./...`
+- `go vet ./...`
+- `staticcheck ./...` (if tool is available locally)
+
+CI verification through PR run:
+- Confirm `fmt`, `test`, `vet`, and `staticcheck` jobs execute on pull requests.
+- Confirm non-zero from `vet`/`staticcheck` marks workflow failed.
+
+## Risks and mitigations
+- Risk: pinned staticcheck version not present in runner cache.
+  - Mitigation: install in-job via `go install` each run.
+- Risk: staticcheck findings on current code block CI.
+  - Mitigation: if encountered, address only findings required to satisfy issue scope.
+
+## Acceptance mapping
+- CI fail on vet errors → `vet` job runs `go vet ./...`.
+- CI fail on staticcheck errors → `staticcheck` job runs pinned staticcheck binary.
+- Existing checks preserved → `fmt` and `test` jobs remain in workflow.
+- No `golangci-lint` → not introduced in workflow.