Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
96 lines (66 loc) · 4.15 KB

CONTRIBUTING.md

File metadata and controls

96 lines (66 loc) · 4.15 KB
Raw

Contributing to Watchtower

Thanks for wanting to help keep this fork alive. The bar is pragmatism, not perfection — small, focused PRs are far more welcome than grand rewrites.

Prerequisites

  • Devbox — the single tool you need. It pins Go, golangci-lint, gofumpt, gci, go-task, ginkgo, docker, and goreleaser at the exact versions CI uses. No global Go install required; no GO111MODULE juggling.
  • Docker — for integration-style runs via docker compose up --build.
curl -fsSL https://get.jetify.com/devbox | bash
git clone git@github.com:<yourfork>/watchtower.git
cd watchtower
devbox shell     # enters the pinned toolchain

Day-to-day

Everything runs through go-task inside Devbox — CI uses the same targets, so green locally means green in CI (barring runner flakes):

devbox run -- task              # list targets
devbox run -- task deps         # go mod download + tidy + vendor
devbox run -- task fmt          # gci + gofumpt
devbox run -- task lint         # golangci-lint (auto-runs fmt first) — must be 0 findings
devbox run -- task test         # full Ginkgo v2 suite with coverage
devbox run -- task build        # ./build/watchtower

Focus a single Ginkgo spec:

devbox run -- go test -mod vendor ./internal/actions -v -ginkgo.focus="the update action"

Spin up the full stack locally (Watchtower + Prometheus + Grafana + a few demo containers):

docker compose up --build

Pull request checklist

  • devbox run -- task lint passes with 0 findings. Fix findings rather than suppress them; if an exclusion is justified, edit .golangci.yml with a reason, not //nolint.
  • devbox run -- task test passes. Tests use Ginkgo v2 + Gomega — prefer extending the existing Describe/It suites over adding plain testing.T tests.
  • devbox run -- task build succeeds.
  • You're editing flags in internal/flags/ (the single source of truth) — not inline in cmd/.
  • Commit message is a short imperative ("Fix X when Y" / "Add Z support for W"). No noise like "update code". The full PR description is where the why belongs.
  • You haven't reintroduced github.com/containrrr/watchtower as a Go import path — the module path is github.com/openserbia/watchtower.
  • Every commit is signed off (git commit -s) — see Developer Certificate of Origin below. A CI check enforces this on pull requests.

Developer Certificate of Origin (DCO)

Contributions to this project require a Developer Certificate of Origin sign-off. The DCO is a lightweight, legally meaningful statement — read the full text at https://developercertificate.org/ — that certifies you wrote the patch, or otherwise have the right to submit it under the project's Apache-2.0 license. It is not a copyright assignment.

You sign off by adding a Signed-off-by trailer to each commit message:

Signed-off-by: Your Name <your.email@example.com>

Git adds it for you with the -s flag:

git commit -s -m "Fix X when Y"

The name and email must be real and match your commit author identity. If you forgot to sign off, add it retroactively across a branch with:

git rebase --signoff <base>

The DCO workflow verifies that every commit in a pull request carries a sign-off; PRs without it will fail the check.

Architecture orientation

For a deeper tour of the codebase — package boundaries, the Cobra/cron scheduling wiring, how actions.Update orchestrates a run, how the Docker client is mocked — see CLAUDE.md. It's written for AI coding assistants but reads well for humans navigating the project for the first time.

Security issues

Do not file public issues for security bugs — use GitHub Security Advisories instead. See SECURITY.md for the full policy.

Governance

Roles, responsibilities, decision-making, and how to become a maintainer are documented in GOVERNANCE.md.

Code of conduct

By participating, you agree to follow the code of conduct.