From e71015135aeafe1b683cd6ef04a5f6cd684d5bc1 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:09 -0700 Subject: [PATCH 1/2] 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 | 44 ++++++++------------------------------------ 1 file changed, 8 insertions(+), 36 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 1c51293..f15ceeb 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -120,42 +120,14 @@ just md-fmt # Auto-fix formatting ## Code standards -### Function Signatures - -ALL function signatures MUST use multi-line format: - -```go -func FunctionName( - param1 type1, - param2 type2, -) (returnType, error) { -} -``` - -### Testing - -- Public tests: `*_public_test.go` in test package (`package orchestrator_test`) - for exported functions -- Internal tests: `*_test.go` in same package (`package orchestrator`) for - private functions -- Suite naming: `*_public_test.go` → `{Name}PublicTestSuite`, `*_test.go` → - `{Name}TestSuite` -- Use `testify/suite` with table-driven patterns -- One suite method per function under test — all scenarios (success, errors, - edge cases) as rows in one table - -### 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) - -### Linting - -golangci-lint with: errcheck, errname, goimports, govet, prealloc, predeclared, -revive, staticcheck. Generated files (`*.gen.go`, `*.pb.go`) are excluded from -formatting. +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. + +In this repository the external test package is `package orchestrator_test`. +Tests exercise a real HTTP server via `httptest.Server` rather than mocking the +SDK client, so no mocking library is declared. ## Testing From 8c822245f812e28ae434bedef6f633856b15a5d2 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:48 -0700 Subject: [PATCH 2/2] 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 | 51 +++++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f15ceeb..e9b6635 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -120,14 +120,53 @@ just md-fmt # Auto-fix formatting ## Code standards -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. + +### 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. + +### Testing + +- Public tests: `*_public_test.go` in `package orchestrator_test`, exercising + the exported surface. This is the default. +- Internal tests: `*_test.go` in `package orchestrator`, for what the exported + surface cannot reach. +- Suite naming: `*_public_test.go` → `{Name}PublicTestSuite`, `*_test.go` → + `{Name}TestSuite`. +- `testify/suite` with table-driven cases. +- One suite method per function under test — success, errors, and edge cases are + rows in one table, not separate methods. -In this repository the external test package is `package orchestrator_test`. Tests exercise a real HTTP server via `httptest.Server` rather than mocking the -SDK client, so no mocking library is declared. +SDK client, so this repository declares no mocking library. + +### 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) + +### Linting + +golangci-lint with: errcheck, errname, goimports, govet, prealloc, predeclared, +revive, staticcheck. Generated files (`*.gen.go`, `*.pb.go`) are excluded from +formatting. ## Testing