How-to info for linting

CLAUDE.md

@@ -6,6 +6,29 @@ Miller is a command-line data processing tool for working with CSV, TSV, JSON, a
 
 ## Initial Setup
 
+### Setting Up golangci-lint
+
+CI runs `golangci-lint` at a pinned version — see `.github/workflows/golangci-lint.yml` for the exact version
+(currently `v2.12.2`). **Always install that exact version locally** to avoid skew between local and CI results.
+
+```bash
+curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.12.2
+```
+
+Verify:
+```bash
+golangci-lint --version
+# golangci-lint has version 2.12.2 ...
+```
+
+Run locally (same flags as CI):
+```bash
+make lint
+# equivalent: golangci-lint run --timeout=5m ./cmd/mlr ./pkg/...
+```
+
+When the CI workflow pins a new version, update your local install to match before running `make lint`.
+
 ### Setting Up staticcheck
 
 The `make staticcheck` target requires the staticcheck tool. To set it up:
@@ -48,6 +71,7 @@ make bench          # Run benchmarks
 ```bash
 make fmt            # Format code with go fmt
 make staticcheck    # Run static analysis (see Initial Setup section above)
+make lint           # Run golangci-lint (see Initial Setup section above)
 ```
 
 ### Full Developer Workflow

Makefile

@@ -79,6 +79,11 @@ fmt format:
 staticcheck:
 	staticcheck ./pkg/... ./cmd/mlr/...
 
+# golangci-lint -- must match the version pinned in .github/workflows/golangci-lint.yml.
+# Install: curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.12.2
+lint:
+	golangci-lint run --timeout=5m ./cmd/mlr ./pkg/...
+
 # ----------------------------------------------------------------
 # For developers before pushing to GitHub.
 #
@@ -125,4 +130,4 @@ release_tarball release-tarball: build check
 
 # ================================================================
 # Go does its own dependency management, outside of make.
-.PHONY: build mlr check unit_test regression_test bench fmt staticcheck dev docs man
+.PHONY: build mlr check unit_test regression_test bench fmt staticcheck lint dev docs man

README-dev.md

@@ -14,6 +14,36 @@
 
 The Go implementation is auto-built using GitHub Actions: see [.github/workflows/go.yml](.github/workflows/go.yml). This works splendidly on Linux, MacOS, and Windows.
 
+## golangci-lint
+
+CI also runs `golangci-lint` on every push and PR: see [.github/workflows/golangci-lint.yml](.github/workflows/golangci-lint.yml).
+
+**Version pinning**: The workflow pins a specific `golangci-lint` version (currently `v2.12.2`). To avoid
+local/CI skew — where your machine passes but CI fails, or vice versa — always install the exact version
+from the workflow file before running lint locally.
+
+Install the pinned version (replace `v2.12.2` if the workflow has been updated):
+
+```bash
+curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/HEAD/install.sh | sh -s -- -b $(go env GOPATH)/bin v2.12.2
+```
+
+Verify:
+
+```bash
+golangci-lint --version
+# golangci-lint has version 2.12.2 ...
+```
+
+Run locally with the same flags CI uses:
+
+```bash
+make lint
+# equivalent: golangci-lint run --timeout=5m ./cmd/mlr ./pkg/...
+```
+
+When the workflow bumps the pinned version, re-run the install command with the new version before linting.
+
 # Benefits of porting to Go
 
 * The lack of a streaming (record-by-record) JSON reader in the C implementation ([issue 99](https://github.com/johnkerl/miller/issues/99)) is immediately solved in the Go implementation.