Skip to content
Shipcheck

Project

Contributing

Shipcheck is small on purpose. The best contributions make existing checks more accurate, clearer or faster.

Repository layout

shipcheck/
cli/                 Go CLI (the tool itself)  cmd/shipcheck/     entry point  internal/app/      commands, flags, exit codes  internal/checks/   one file per check  internal/config/   .shipcheck.yml parsing and validation  internal/detector/ test, build and version detection  internal/output/   text and JSON renderers  internal/project/  filesystem and Git helpers  internal/runner/   runs checks, applies severity  tests/             end-to-end tests against the real binaryweb/                 this website (Next.js)docs/                documentation in Markdown

Working on the CLI

You need Go 1.22 or newer and Git.

bash
$ cd cli$ go test ./...$ go run ./cmd/shipcheck --dir .. --verbose

Tests create real temporary projects and Git repositories, so they need no fixtures and no network. Please add a test for every behaviour change.

Adding a check

A check is a value with an ID, a name, a description and a Run function. The runner handles timing, severity, enabling and output, so a check only decides its result.

cli/internal/checks/changelog.go
// cli/internal/checks/changelog.gopackage checksimport "context"// Changelog checks for a CHANGELOG file.var Changelog = Check{	ID:          "changelog",	Name:        "Changelog",	Description: "Checks for a CHANGELOG.md.",	Run: func(_ context.Context, env *Env) Result {		if name := env.Project.FindFile("CHANGELOG.md"); name != "" {			return pass("Changelog found", name)		}		return Result{			Status:     Warn,			Message:    "No changelog",			Suggestion: "Add a CHANGELOG.md so users know what changed.",		}	},}
  1. Add it to All() in cli/internal/checks/checks.go, in the position it should run.
  2. Add tests next to it. The existing tests show how to build a throwaway project with testutil.Dir.
  3. Document it in web/lib/checks.ts and docs/checks.md.

Working on the website

You need Node.js 20.9 or newer.

bash
$ cd web$ npm install$ npm run dev$ npm run lint && npm run build

The site is static: no database, no API routes, no analytics. Terminal examples are copied from real CLI output, so update them when CLI messages change.

Pull requests

  • Open an issue first for new checks or larger changes, so we can agree on scope.
  • Keep pull requests focused on one change.
  • Run gofmt, go vet ./... and go test ./... for CLI changes, and npm run lint and npm run build for website changes.
  • Follow the code of conduct.

The full guide is in CONTRIBUTING.md. Issues and pull requests live on GitHub. New to Shipcheck? Start with the documentation.