docs: add gauge-repo engineering best-practices audit - #119
Merged
Conversation
Contributor
There was a problem hiding this comment.
🟡 Changes recommended
The new audit doc contains a few verified incorrect/inconsistent references (notably file paths and Go version alignment) that should be corrected to avoid misleading guidance.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Adds a new repository audit document capturing a gauge-repo “engineering best practices” assessment for caterpillar, including score totals, per-category breakdowns, evidence, and prioritized remediation recommendations.
Changes:
- Introduces
docs/engineering-best-practices-audit.mdwith an audit scorecard and critical gate callouts. - Documents per-item evidence and recommendations across documentation, guardrails, testing, and tooling categories.
- Lists prioritized remediation steps intended to raise compliance and satisfy critical gates.
File summaries
| File | Description |
|---|---|
docs/engineering-best-practices-audit.md |
Adds the best-practices audit writeup, evidence, and recommendations for the repo. |
Review details
Suppressed comments (1)
docs/engineering-best-practices-audit.md:142
- This recommendation hard-codes Go 1.24.7, but
go.modcurrently declares Go 1.25.0. Either avoid a specific version here or base it ongo.modand note that CI/Dockerfile should be aligned to the same version.
22. **[S] Gap — devcontainer (item 36):** Add `.devcontainer/` pinned to Go 1.24.7 + Alpine 3.20 + librdkafka to match `build/Dockerfile`.
- Files reviewed: 1/1 changed files
- Comments generated: 2
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| | 40 | Scoped secrets per environment | **Partial** | Release workflow uses GitHub `secrets.DOCKERHUB_USERNAME`/`DOCKERHUB_TOKEN`; runtime pipelines pull via AWS Parameter Store (`{{ secret "/prod/api/token" }}`), but there is no documented dev/staging/prod scoping convention | Document the dev/stage/prod SSM prefix layout in README/AGENTS and validate the prefix at pipeline load. Critical gate. | | ||
| | 41 | Preview environments per PR | **Not applicable** | Distributable CLI + library, not a deployed hosted service | — | | ||
| | 42 | Hot-reload / watch mode | **Not applicable** | Go compile-and-run CLI; pipeline runs are batch — no long-running dev-server surface for hot-reload | — | | ||
| | 43 | Structured logging (JSON) | **Gap** | `internal/pkg/pipeline/pipeline.go` and `pipeline/task/task.go` use `fmt.Println` for status/errors; no `log/slog` or structured logger | Switch to `log/slog` with JSON output and include task name, record ID, and pipeline run ID. | |
| | 45 | Feature flags with local overrides | **Gap** | No `patterninc/toggles-go` or LaunchDarkly integration | Add a lightweight flag hook (env-var overrides in dev) for opt-in features like DAG mode, once it exits EXPERIMENTAL. | | ||
| | 46 | Database migration tooling | **Not applicable** | Repo owns no database | — | | ||
| | 47 | Dependency update automation | **Met** | Inherited Pattern Wiz policy for verified `patterninc` repos | — | | ||
| | 48 | Reproducible builds (lockfiles) | **Met** | `go.mod` + `go.sum` pinned; Dockerfile pins Alpine 3.20 + Go 1.24.7; release workflow uses matching Go version. Critical gate. | — | |
Naman Sharma (ns1306)
approved these changes
Sep 9, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds the gauge-repo engineering best-practices audit for
caterpillaratdocs/engineering-best-practices-audit.md(data-platform catalog batch).go build— nogo testor lint), and 40 (scoped secrets lack a documented dev/stage/prod SSM layout) are not MetAGENTS.mdat repo root (build/test commands, per-task README convention).github/workflows/ci.yamlto rungo test ./...andgolangci-lint, then require both in the rulesetDocumentation only — no code changes.
Requested by: juili.chormole@pattern.com