Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
73 lines (49 loc) · 3.48 KB

CONTRIBUTING.md

File metadata and controls

73 lines (49 loc) · 3.48 KB
Raw

Contributing to cipher

Patches welcome. This document covers how to get set up, what the CI runs, and what to expect during review.

Development environment

  • Go 1.25 or newer.
  • A working gpg binary if you plan to touch the PGP backend.
  • golangci-lint for the lint workflow.
  • goreleaser if you plan to touch release configuration.

Setup

git clone https://github.com/dcadolph/cipher
cd cipher
make build
make test
make lint

Run make help for every available target.

What CI runs

Workflow Trigger What it does
test push to main, pull request go test ./... on Linux and macOS with Go 1.26.x. Coverage is uploaded as a build artifact on each run.
lint push to main, pull request golangci-lint run.
integration push to main, pull request Starts a dev vault container, runs the integration tag tests against it.
bench manual dispatch, push to main that touches Go files Runs the benchmark suite and posts the output.
release tag push matching v* GoReleaser builds binaries, publishes the GitHub release, pushes the Homebrew cask. See RELEASING.md.

Run the same checks locally before opening a pull request to avoid round trips. Integration tests need a running vault and the integration build tag, e.g. VAULT_ADDR=http://localhost:8200 VAULT_TOKEN=root go test -tags integration ./vault/.

Coverage

The test workflow writes coverage.out on the Linux run, prints the total to the job log, and uploads the profile as a build artifact with 14 day retention. Download it from the run page and open it locally:

go tool cover -html=coverage.out

Commit and PR style

  • Imperative, short subjects under 72 characters. Add walk progress reporting. not Added walk progress reporting and fixed the bug.
  • Body explains the why, not the what, unless the change is obvious from the diff.
  • One logical change per commit. Squash review fixups before merge.
  • PR titles follow the same convention as commit subjects.
  • PR descriptions cover summary, test plan, and any visible behavior change worth a screenshot.

Tests

  • Table-driven. See existing *_test.go files for the project's house style.
  • t.Parallel() at the top of every test that does not share global state.
  • Use github.com/google/go-cmp/cmp for diffing. The project does not use testify.
  • Fixtures go under testdata/ per package.

Backends

Backend tests that need cloud credentials are skipped without them. Set the relevant environment variable (AWS_PROFILE, GOOGLE_APPLICATION_CREDENTIALS, VAULT_TOKEN plus VAULT_ADDR, Azure CLI, gpg keyring) to opt in.

Reporting bugs

Open a GitHub issue using the bug template. For security reports use GitHub Security Advisories per SECURITY.md. Do not open public issues for vulnerabilities.

Proposing features

Open an issue using the feature template before writing code for non-trivial changes. Aligning on shape early saves rework.

License

Patches are submitted under the same Apache-2.0 license as the rest of the project. By opening a pull request you agree to license your contribution under those terms.