From e0b53eaeff8121485a264a866aefd25ba8ad740d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 4 Sep 2026 13:23:25 -0700 Subject: [PATCH 1/5] fix: name the revive rules instead of enabling all of them MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The file said version 2 and then held linters-settings at the top level, which is the v1 layout. golangci-lint drops keys it does not recognise without complaining, so enable-all-rules never applied and most of revive has been switched off for as long as that line has been there. Turning it on properly reported 1,363 findings across these repositories. Almost all of it was naming constants and splitting functions to satisfy a threshold — line-length-limit, cognitive-complexity, cyclomatic, function-length and add-constant each report on a number somebody picked rather than on a defect. So the rules are named individually now, and the list is the conventions Go itself has an opinion about. Against this repository's current code that reports zero, which is the point: nothing to schedule, and the next mistake gets caught. Go vendored inside a JavaScript dependency tree is excluded — flatted ships a Go port beside its JS, is not tracked in git, and was the only thing govet reported anywhere. ineffassign joins the list, and the max-issues and uniq-by-line settings stop the output being truncated at 50 findings per linter and one finding per line. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- .golangci.yml | 76 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 51 insertions(+), 25 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index 3438e8e08..0f9bd4fa0 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,50 +1,76 @@ -# Refer to golangci-lint's example config file for more options and information: -# https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml +# golangci-lint v2 configuration. +# https://golangci-lint.run/docs/configuration/file/ +# +# One config, byte for byte identical in every Go repository in osapi-io and +# in @retr0h/golang-starter, which new projects are generated from. A +# repository that needs a change to it changes it in the template too, and +# the change goes back out to the others in the same pass. `md5 .golangci.yml` +# in each repository is how you check. +# +# `version` is the string "2" and settings nest under `linters`. Written the +# v1 way — a numeric version, a top-level `linters-settings`, an +# `issues.exclude-use-default` — `run` drops the keys without complaint and +# nothing takes effect. `golangci-lint config verify` is the check. -version: 2 +version: "2" run: timeout: 5m - modules-download-mode: readonly linters: enable: - errcheck - errname - govet + - ineffassign - prealloc - predeclared - revive - staticcheck - unused + + settings: + revive: + # Named rules only, not enable-all-rules. Every rule here states a + # convention Go itself has an opinion about. Rules that measure — a + # line length, a complexity score, a count of constants — are left + # out: the number is somebody's taste, not the language's. + rules: + - name: error-naming + - name: error-return + - name: error-strings + - name: errorf + - name: exported + - name: increment-decrement + - name: indent-error-flow + - name: range + - name: receiver-naming + - name: superfluous-else + - name: time-naming + - name: unused-parameter + - name: var-naming + exclusions: paths: - - ui/node_modules - rules: - - linters: - - revive - path: internal/api/ - text: "var-naming: avoid meaningless package names" - - linters: - - revive - path: internal/exec/ - text: "var-naming: avoid package names that conflict with Go standard library package names" - - linters: - - revive - path: internal/api/metrics/ - text: "var-naming: avoid package names that conflict with Go standard library package names" + # Go source vendored inside a JavaScript dependency tree is not ours + # to fix, and is not even tracked in git: `flatted` ships a Go port + # beside its JS, and it only exists after npm install. + - node_modules + presets: + - comments + - std-error-handling formatters: enable: + - gofmt - goimports -linters-settings: - revive: - enable-all-rules: true - issues: - exclude-use-default: false + # Without these every run stops at 50 findings per linter and the + # repository looks like it has exactly 50 problems, forever. max-issues-per-linter: 0 max-same-issues: 0 - exclude-dirs: - - ./client + # Default true, which reports one finding per line. Several rules anchor + # to the same function declaration, so one line can carry more than one + # and you are shown whichever came first. + uniq-by-line: false From f105688c64d66cd7aa69f5257572d377cde67dff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 4 Sep 2026 13:24:47 -0700 Subject: [PATCH 2/5] docs: reword the comment so it does not name the setting it rejects The template test asserts the config does not switch on the whole rule set. The comment explaining why said so in those words, and the test matched its own explanation. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- .golangci.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index 0f9bd4fa0..63920cc14 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -31,10 +31,10 @@ linters: settings: revive: - # Named rules only, not enable-all-rules. Every rule here states a - # convention Go itself has an opinion about. Rules that measure — a - # line length, a complexity score, a count of constants — are left - # out: the number is somebody's taste, not the language's. + # Each rule is named rather than the whole set switched on. Every + # one here states a convention Go itself has an opinion about. + # Rules that report a threshold are left out: the number is + # somebody's taste, not the language's. rules: - name: error-naming - name: error-return From f8e301eb92f43ee4398b2d46d7f74c1a55801c6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 4 Sep 2026 13:28:43 -0700 Subject: [PATCH 3/5] docs: cut the comments back to what is not obvious from the file Twenty-five of seventy-six lines were comment, and most of it explained history rather than the file. The paragraph about v1 keys under a v2 version described a bug this file no longer has, and `config verify` catches it anyway. What stays is the three things reading the file will not tell you: that it is shared and must be changed everywhere at once, that the rule list is deliberate rather than partial, and that golangci-lint truncates its own output by default. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- .golangci.yml | 29 +++++++---------------------- 1 file changed, 7 insertions(+), 22 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index 63920cc14..c6d405a6b 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,16 +1,9 @@ # golangci-lint v2 configuration. # https://golangci-lint.run/docs/configuration/file/ # -# One config, byte for byte identical in every Go repository in osapi-io and -# in @retr0h/golang-starter, which new projects are generated from. A -# repository that needs a change to it changes it in the template too, and -# the change goes back out to the others in the same pass. `md5 .golangci.yml` -# in each repository is how you check. -# -# `version` is the string "2" and settings nest under `linters`. Written the -# v1 way — a numeric version, a top-level `linters-settings`, an -# `issues.exclude-use-default` — `run` drops the keys without complaint and -# nothing takes effect. `golangci-lint config verify` is the check. +# Identical in every osapi-io Go repository and in @retr0h/golang-starter, +# which new projects come from. Change it here too, and `md5 .golangci.yml` +# is how you check they still match. version: "2" @@ -31,10 +24,8 @@ linters: settings: revive: - # Each rule is named rather than the whole set switched on. Every - # one here states a convention Go itself has an opinion about. - # Rules that report a threshold are left out: the number is - # somebody's taste, not the language's. + # Named rules, not the whole set: these are conventions Go itself + # has an opinion about. Rules that report a threshold are left out. rules: - name: error-naming - name: error-return @@ -52,9 +43,7 @@ linters: exclusions: paths: - # Go source vendored inside a JavaScript dependency tree is not ours - # to fix, and is not even tracked in git: `flatted` ships a Go port - # beside its JS, and it only exists after npm install. + # Go shipped inside a JS package. Not ours, and not tracked in git. - node_modules presets: - comments @@ -66,11 +55,7 @@ formatters: - goimports issues: - # Without these every run stops at 50 findings per linter and the - # repository looks like it has exactly 50 problems, forever. + # Defaults truncate: 50 findings per linter, and one per line. max-issues-per-linter: 0 max-same-issues: 0 - # Default true, which reports one finding per line. Several rules anchor - # to the same function declaration, so one line can carry more than one - # and you are shown whichever came first. uniq-by-line: false From b4a9ca55ad8e24a7aeec4219447ac0a6129fd515 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 4 Sep 2026 13:30:07 -0700 Subject: [PATCH 4/5] docs: drop the pointer to where the template lives Someone reading nats-client's config does not care that a swamp extension generates new projects from the same file. The rule that matters is that it is shared and changes go everywhere at once. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- .golangci.yml | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index c6d405a6b..c8a10b6e7 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,9 +1,8 @@ # golangci-lint v2 configuration. # https://golangci-lint.run/docs/configuration/file/ # -# Identical in every osapi-io Go repository and in @retr0h/golang-starter, -# which new projects come from. Change it here too, and `md5 .golangci.yml` -# is how you check they still match. +# This file is the same in every Go repository here. Change it in all of +# them at once; `md5 .golangci.yml` is how you check they still match. version: "2" From e7d34083b3a5f2108ac487b1a31827c5a6f7ec0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=D7=A0=CF=85=CE=B1=CE=B7=20=D7=A0=CF=85=CE=B1=CE=B7=D1=95?= =?UTF-8?q?=CF=83=CE=B7?= Date: Fri, 4 Sep 2026 13:33:02 -0700 Subject: [PATCH 5/5] docs: drop the comment asking people to keep the file in sync Nothing checked it. A comment stating a policy that no test enforces is a wish, and the six remaining lines all explain a setting that is not obvious from reading it. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01FuKUsHFG1EqZXamffh9M2c --- .golangci.yml | 3 --- 1 file changed, 3 deletions(-) diff --git a/.golangci.yml b/.golangci.yml index c8a10b6e7..f8cbb79a9 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,8 +1,5 @@ # golangci-lint v2 configuration. # https://golangci-lint.run/docs/configuration/file/ -# -# This file is the same in every Go repository here. Change it in all of -# them at once; `md5 .golangci.yml` is how you check they still match. version: "2"