From 1d91f803b801c0d930ec5e6816b91fe9577287e1 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: Sat, 15 Aug 2026 23:30:07 -0700 Subject: [PATCH 1/3] docs: point Go conventions at the capability The shared conventions are specified once in go-code-standards. CONTRIBUTING.md keeps the commands a contributor runs and whatever is genuinely specific to this repository. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 59 ++++++------------------------------------------- 1 file changed, 7 insertions(+), 52 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 55c59a2..3d9a4cf 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,10 +58,10 @@ just deps ## Code style -### Go - -Go code should be formatted by [gofumpt] and linted using [golangci-lint]. This -style is enforced by CI. +Go conventions — signatures, file naming, test structure, mocking, and the style +baseline — are specified in the `go-code-standards` capability in +[osapi-io/specs](https://github.com/osapi-io/specs). Where this page and the +specification disagree, the specification wins. ```bash just go-fmt-check # Check formatting @@ -69,40 +69,7 @@ just go-fmt # Auto-fix formatting just go-vet # Run linter ``` -golangci-lint runs errcheck, errname, goimports, govet, prealloc, predeclared, -revive, and staticcheck. Generated files (`*.gen.go`, `*.pb.go`) are excluded -from formatting. - -### Function signatures - -Functions with parameters MUST use multi-line format: - -```go -func FunctionName( - param1 type1, - param2 type2, -) (returnType, error) { -} -``` - -### Go patterns - -- Error wrapping: `fmt.Errorf("context: %w", err)` -- Early returns over nested if-else -- Unused parameters: rename to `_` -- Import order: stdlib, third-party, local (blank-line separated) -- Avoid generic file names like `helpers.go` or `utils.go` — name files after - what they contain - -### Documentation - -Markdown files are formatted with [mdformat] through `uvx`. This style is -enforced by CI. - -```bash -just md-fmt-check # Check formatting -just md-fmt # Auto-fix formatting -``` +Generated files (`*.gen.go`, `*.pb.go`) are excluded from formatting. ## Testing @@ -125,18 +92,8 @@ module — change both together. ### Test file conventions -- Public tests: `*_public_test.go` in test package (`package server_test`) for - exported functions. -- Internal tests: `*_test.go` in the same package (`package server`) for private - functions. -- Suite naming: `*_public_test.go` → `{Name}PublicTestSuite`, `*_test.go` → - `{Name}TestSuite`. -- Use `testify/suite` with table-driven patterns and `validateFunc` callbacks. -- **One suite method per function under test.** All scenarios for a function - (success, error codes, transport failures, nil responses) belong as rows in a - single table — never split into separate `TestFoo`, `TestFooError`, - `TestFooNilResponse` methods. -- Use `go.uber.org/mock` for mocking interfaces. +Test structure, suite naming, and mocking are specified in `go-code-standards`. +In this repository the external test package is `package server_test`. ## Before committing @@ -211,8 +168,6 @@ If you have questions, feel free to open a [Discussion] on GitHub. [conventional commits]: https://www.conventionalcommits.org [discussion]: https://github.com/osapi-io/nats-server/discussions [go]: https://go.dev -[gofumpt]: https://github.com/mvdan/gofumpt -[golangci-lint]: https://golangci-lint.run [just]: https://just.systems [mdformat]: https://pypi.org/project/mdformat/ [mise]: https://mise.jdx.dev From 711436e4e9a26a96eecc7b0f36482583c5f738ed 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: Sat, 15 Aug 2026 23:35:46 -0700 Subject: [PATCH 2/3] docs: restate the conventions rather than only linking them The first pass replaced the shared Go conventions with a pointer, which left a contributor unable to learn how to write code here without reading another repository. It also dropped the suite naming convention entirely, since the capability did not yet state it. Keep the substance and the examples; the pointer establishes which statement is authoritative. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 50 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 43 insertions(+), 7 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3d9a4cf..b9ac7c7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -58,10 +58,14 @@ just deps ## Code style -Go conventions — signatures, file naming, test structure, mocking, and the style -baseline — are specified in the `go-code-standards` capability in -[osapi-io/specs](https://github.com/osapi-io/specs). Where this page and the -specification disagree, the specification wins. +These conventions are shared across every Go repository in the organization and +are specified in the `go-code-standards` capability in +[osapi-io/specs](https://github.com/osapi-io/specs). They are restated here +because a contributor should not have to read another repository to learn how to +write code in this one. Where the two disagree, the specification wins. + +Go code is formatted by [gofumpt] and linted using [golangci-lint], enforced by +CI. ```bash just go-fmt-check # Check formatting @@ -69,7 +73,30 @@ just go-fmt # Auto-fix formatting just go-vet # Run linter ``` -Generated files (`*.gen.go`, `*.pb.go`) are excluded from formatting. +golangci-lint runs errcheck, errname, goimports, govet, prealloc, predeclared, +revive, and staticcheck. Generated files (`*.gen.go`, `*.pb.go`) are excluded +from formatting. + +### Function signatures + +Functions with parameters use multi-line format, one parameter per line: + +```go +func FunctionName( + param1 type1, + param2 type2, +) (returnType, error) { +} +``` + +Zero-parameter functions stay on one line. + +### Go patterns + +- Error wrapping: `fmt.Errorf("context: %w", err)` +- Early returns over nested if-else +- Unused parameters: rename to `_` +- Import order: stdlib, third-party, local (blank-line separated) ## Testing @@ -92,8 +119,17 @@ module — change both together. ### Test file conventions -Test structure, suite naming, and mocking are specified in `go-code-standards`. -In this repository the external test package is `package server_test`. +- Public tests: `*_public_test.go` in `package server_test`, exercising the + exported surface. This is the default. +- Internal tests: `*_test.go` in `package server`, for what the exported surface + cannot reach. +- Suite naming: `*_public_test.go` → `{Name}PublicTestSuite`, `*_test.go` → + `{Name}TestSuite`. +- `testify/suite` with table-driven cases and `validateFunc` callbacks. +- One suite method per function under test — all scenarios for a function + (success, error codes, transport failures, nil responses) are rows in one + table, never separate `TestFoo` / `TestFooError` methods. +- Mocks are generated with `go.uber.org/mock` and committed; never hand-written. ## Before committing From 75dc7e4f2681fb22c870818d4501f20ddf2f4c26 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: Sat, 15 Aug 2026 23:39:02 -0700 Subject: [PATCH 3/3] docs: restore the markdown formatting section A broad replacement between Code style and Testing swept up the Documentation subsection, which covers markdown rather than Go and had nothing to do with the conventions being moved. Co-Authored-By: Claude Opus 5 (1M context) --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b9ac7c7..fced269 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -98,6 +98,16 @@ Zero-parameter functions stay on one line. - Unused parameters: rename to `_` - Import order: stdlib, third-party, local (blank-line separated) +### Documentation + +Markdown files are formatted with [mdformat] through `uvx`. This style is +enforced by CI. + +```bash +just md-fmt-check # Check formatting +just md-fmt # Auto-fix formatting +``` + ## Testing ```bash