484dc7dd07
fix: update drifted file:line citations in Go patterns
...
Upstream golang/go has shifted several line numbers since citations
were recorded. Updated 6 citations across 3 files:
- documentation.md: server.go:55-57 → 59-62 (ErrWriteAfterFlush)
- documentation.md: transport.go:79-80 → 72-73 (Transports should be reused)
- structs.md: client.go:31-35 → 30-34 (A Client is an HTTP client)
- structs.md: client.go:59-60 → 57-58 (type Client struct)
- style.md: stream.go:280 → 292 (var _ Marshaler)
- style.md: stream.go:280-281 → 292-293 (var _ Marshaler/Unmarshaler)
Verified against golang/go HEAD (depth=1 clone).
2026-05-27 05:52:38 +00:00
52a3629583
fix: correct drifted line citations in time/time.go and net/http/server.go
...
- time/time.go:928-933 -> 925-933 ("To count the number of units" block starts at 925)
- time/time.go:936-943 -> 934-942 (const Duration block starts at 934)
- net/http/server.go:3173-3174 -> 3171-3174 (Close() func starts at 3171)
2026-05-18 15:07:04 +00:00
f070fef8ee
fix(citations): correct NewServeMux citation in package-design.md
...
server.go:2639 → 2638 (function declaration line)
Body drift: 'return new(ServeMux)' → 'return &ServeMux{}'
2026-05-11 08:04:32 -07:00
befe49257a
docs: rewrite usage section as agent instructions
...
Frame the README for someone setting up a subagent that uses
this repo as a knowledge base. Three prompt templates:
solving problems, reviewing code, evaluating patterns.
2026-05-07 18:06:55 -07:00
a8e2020bc4
docs: add usage prompts for writing, reviewing, and evaluating
2026-05-07 18:06:07 -07:00
be394efd0b
docs: define patterns vs conventions in README
...
Patterns are prescriptive — follow them.
Conventions are descriptive — study for ideas.
Clarifies repo purpose, directory structure, and how to
use patterns during development and review.
2026-05-07 18:04:50 -07:00
65a433d0c6
chore: merge golang-conventions and prometheus-conventions into sources/
...
Absorbed content from rodin/golang-conventions and
rodin/prometheus-conventions into a sources/ directory.
Reference material — descriptive, not prescriptive.
Part of taxonomy cleanup (elixir-patterns issue #4 ).
2026-05-07 18:02:04 -07:00
0de5f54365
fix: correct drifted citation for tls.Config.Clone
...
crypto/tls/common.go#L925 was wrong; the Clone() method is at L996
in commit 17bd5ab8c650155dd2bd09f7005726552639eea0.
Audited all citations across all pattern .md files — only this one
had drifted. All others verified OK against the pinned golang/go commit.
2026-05-06 17:21:18 -07:00
52503d24c2
fix: update drifted file:line citations to match current golang/go source
...
Audited all file:line citations against golang/go HEAD.
97 citations checked; 9 had drifted by 1-20 lines (off-by-one or small
structural shifts in the stdlib source). Updated both inline code block
comments and corresponding GitHub #L anchor links.
Changes per file:
patterns/api-conventions.md - strings/builder.go WriteString (92→112), String (48→46)
patterns/configuration.md - crypto/tls/common.go Time field (572→575)
patterns/documentation.md - net/http/server.go Handler comment (64→65), os/file.go example (17→16)
patterns/structs.md - os/types.go File struct (16→15), strings/builder.go copyCheck (25→32)
patterns/style.md - net/http/server.go TLSConfig (3041→3040), import block (8→9)
2026-05-06 17:17:20 -07:00
7bcc1cc62b
docs: rewrite anti-patterns as general Go smells (was Kubernetes-only)
...
Previous version was entirely Kubernetes controller-specific (from
kubernetes-conventions extraction). Replaced with 10 general Go
anti-patterns from studying golang/go stdlib.
Patterns: error+value returns, large interfaces, init() abuse,
stuttering names, naked returns, error formatting, channel misuse,
returning interfaces, panic in libraries, interface placement.
2026-04-30 16:03:43 -07:00
ffcc0fccf3
chore: remove leftover tooling artifacts (watermark, changelog)
2026-04-30 15:49:25 -07:00
d73c81dab1
Add common-mistakes.md: 10 Go code smells from other languages
...
Covers nil-check-after-use, goroutine leaks, interface pollution,
stuttering names, init() abuse, ignored errors, interface-returning
constructors, mutex value copying, channel misuse, and premature
abstraction. Each entry includes BAD/GOOD examples, trigger conditions,
and exceptions.
2026-04-30 15:46:03 -07:00
c8ed244a07
feat: add source hyperlinks (commit SHA permalinks) to all pattern files
...
Every source reference now links to the exact line in the golang/go
repo at commit 17bd5ab. Added PATTERN_COMPLETE sentinels.
Total: 154 hyperlinks across 10 topic files.
2026-04-30 14:42:20 -07:00
99c0865e93
docs: add configuration.md (skill test output), remove thin from-source.md
...
10 patterns, 989 lines. Full skill spec compliance:
- Source hyperlinks (commit SHA permalinks)
- Before/after code examples for every pattern
- Over-application warnings with code
- Anti-patterns with DON'T/DO blocks
- Decision tree at end
- Cross-references to related topic files
Patterns: zero-value config, options struct, functional options,
default instances, init-time registration, context values,
builder (anti-pattern), function fields, immutable-after-use, Clone.
2026-04-30 14:26:31 -07:00
c7e61565c0
docs: full iterative patterns extraction from golang/go
...
794 lines, 35+ patterns across 9 topics with hyperlinked sources.
Includes frequency data from the source (281 interfaces, 55 sentinels,
262 constructors, 309 context-accepting functions, 2685 t.Helper calls).
Topics: interfaces, errors, testing, packages, concurrency,
documentation, naming, configuration, extension, performance, smells.
All examples are real code from the Go source, not invented.
2026-04-30 13:45:02 -07:00
dfe03e0675
fix: add 'When to use' to every pattern (was missing)
2026-04-30 13:29:50 -07:00
65cae45f13
docs: add patterns extracted from golang/go source
...
Using codebase-analysis skill (patterns mode) on the language source.
Real examples from the repo, not invented. Each pattern has:
- Rule, Example, Why, When NOT to use, Source file.
Topics: interface design, error handling, testing, package org,
concurrency, documentation, naming, smells.
2026-04-30 13:26:29 -07:00
fe74d5d47c
chore: remove project conventions from sources/
...
These have been promoted to standalone repos:
- rodin/cockroachdb-conventions
- rodin/prometheus-conventions
- rodin/temporal-conventions
2026-04-30 11:45:45 -07:00
498a3e9b27
docs: add Temporal patterns (9 patterns from temporalio/temporal)
...
Key patterns:
- Effect buffer (transactional side effects with rollback)
- Soft assertions (log invariant violations, don't crash)
- Type-safe state transitions (HSM with source validation)
- Mutable vs immutable context (type-level access control)
- Goroutine Handle (safe lifecycle, predates CockroachDB by 3.5y)
- Dynamic config with generics (566 settings, namespace-scoped)
- Composable predicates (filter algebra with flattening)
- Persistence plugin registration (init pattern)
- ShutdownOnce (CAS-based safe channel close)
2026-04-30 11:40:31 -07:00
2f7536766c
chore: move cross-ecosystem analysis to patterns-vs-guidelines
...
These docs analyze multiple ecosystems (Go + Elixir) and
don't belong in a single-ecosystem patterns repo.
2026-04-30 10:50:36 -07:00
4185747da6
docs: testing philosophy + API evolution strategies
...
Four testing models: defense-in-depth (CockroachDB), golden
files (Prometheus), fake adapters (Ecto), testing modes (Oban).
Three evolution strategies: version gates (distributed),
numbered migrations (schema), compile-time deprecation (library).
2026-04-30 10:33:55 -07:00
d6f36b67c8
docs: cross-cutting concerns analysis (logging, config, retry, lifecycle)
...
How CockroachDB, Prometheus, Ecto, and Oban handle the
things that touch everything but belong nowhere. Includes
red flags and review questions for each concern.
2026-04-30 10:31:19 -07:00
cee58e85a4
docs: ecosystem-level analysis — how codebases present to consumers
...
Extension points, deliberate absences, test architecture,
and consumer contracts across CockroachDB, Prometheus, Ecto, Oban.
Key insight: smaller interface → larger ecosystem.
2026-04-30 10:02:07 -07:00
725308c37a
docs: architectural analysis across CockroachDB, Prometheus, Ecto, Oban
...
Not just per-file patterns — structural analysis of how these
codebases organize at scale. Key findings:
- 116 packages @ 4 files each (CockroachDB)
- Interface layer breaks circular deps
- Testability designed in, not bolted on
- Composition via data, not inheritance
2026-04-30 09:28:03 -07:00
758ae5dae4
docs: add patterns extracted from cockroachdb and prometheus
...
CockroachDB: 4 patterns (Stopper lifecycle, leak detection, two-phase shutdown, CloserFn adapter)
Prometheus: 5 patterns (atomic file ops, DefaultOptions, aligned timestamps, sentinel errors, compile-time interface checks)
2026-04-30 09:04:11 -07:00
1ef2a4a189
changelog: 2026-04-30 digest
2026-04-30 14:07:37 +00:00
aweiker
733aa7d261
docs: add when-not to style + smells (package-design + documentation already done)
2026-04-30 13:31:47 +00:00
aweiker
11048ae73e
docs: add when-not to interfaces + error-handling + concurrency
2026-04-30 13:26:20 +00:00
aweiker
a7a853bb43
docs: add when-not to structs + testing-advanced + api-conventions
2026-04-30 13:24:01 +00:00
aweiker
631be02392
refactor: remove Kubernetes content (moved to rodin/kubernetes-patterns)
2026-04-30 12:10:11 +00:00
aweiker
eb9171368b
docs: add 'when to use' triggers + examples to all patterns
...
Added 'When to Use' subsections with concrete decision triggers and
before/after Go code examples to patterns across all directories:
- patterns/error-handling.md (3 patterns: sentinels, wrapping, Join)
- patterns/concurrency.md (4 patterns: Mutex, Once, done channels, pipelines)
- patterns/interfaces.md (4 patterns: small interfaces, accept/return, adapter, optional)
- patterns/structs.md (3 patterns: zero-value, constructors, config structs)
- patterns/package-design.md (3 patterns: internal/, init(), context keys)
- patterns/style.md (3 patterns: interface checks, iota constants, named types)
- patterns/testing-advanced.md (3 patterns: table tests, golden files, httptest)
- patterns/api-conventions.md (3 patterns: Must, layered API, graceful shutdown)
- patterns/documentation.md (2 patterns: examples, deprecated)
- kubernetes/patterns.md (3 patterns: controller, workqueue, leader election)
- kubernetes/production-go.md (2 patterns: codegen, HandleCrash)
- smells/anti-patterns.md (2 anti-patterns: cache mutation, edge-triggered)
2026-04-30 12:08:41 +00:00
rodin
0e5974f39a
add MIT license
2026-04-30 11:58:36 +00:00
c797178fb9
docs: idiomatic Go patterns from stdlib + Kubernetes with source citations
2026-04-30 11:07:33 +00:00
0f1d7e4c06
feat: initial Go patterns guide from stdlib + Kubernetes source study
...
9 pattern files covering stdlib (structs, interfaces, API conventions, docs, style),
Kubernetes (controller/reconciler, informer/cache, leader election, code generation),
comparison (stdlib vs K8s approaches), and anti-patterns.
All patterns cite exact source files and line numbers.
2026-04-30 06:34:02 +00:00
Rodin
Rodin
aweiker
rodin