9 Commits

Author SHA1 Message Date
Rodin 324c1936f4 docs: language source comparison — Go vs Elixir source conventions
How do the language teams build their own languages?

Key findings:
- Go: 3,428 owned TODOs (permanent, documenting limitations)
- Elixir: 127 version-gated TODOs (time-bombs with deadlines)
- Go: unsafe is 5th most-imported in its own source (1,304 times)
- Elixir: type system (13K lines) nearly as large as Kernel
- Go: 61 internal/ packages (shared-but-not-public pattern)
- Elixir: 1:1.2 test ratio vs Go's 1:3.3
- Both accept generated code, different delivery (checked-in vs compile-time)
2026-04-30 12:19:32 -07:00
Rodin 91b62be330 docs: add Temporal architectural analysis
8,958 commits, 290 contributors, heavyweight Go infrastructure.

Key findings:
- HSM framework: type-safe state transitions, source validation
- CHASM: mutable vs immutable contexts enforced at type level
- goro.Handle: predates CockroachDB's Handle by 3.5 years (same solution)
- softassert: production assertions that log, don't crash
- 566 dynamic config settings with namespace-scoped resolution
- uber/fx for DI (justified by genuine service graph complexity)
- Domain error types → gRPC mapping (not generic wrapping)

PR discussions show:
- HSM (#5494): 'not final, step in the right direction' — explicit iteration
- CHASM (#6987): separate contexts to make mutation impossible in read paths
- goro.Handle (#1892): born from double-close panic, reviewer rule: 'if expert asks, code needs comment'
2026-04-30 11:38:51 -07:00
Rodin 7e99faff59 docs: PR discussion analysis — how new patterns are debated and landed
Real PR threads from CockroachDB, Prometheus, and Oban showing:
- Handle pattern (PR #142059): 2.5 months, trace span issues discovered in review
- slog migration (PR #14906): 'merge and iterate', 162 files, one commit for 3.0
- AppenderV2 (issue #17632): maintainer pushback defeated by 'it's not user-facing'
- Oban inline testing (PR #684): <24h, zero discussion, solo maintainer

Key insight: 'merge and iterate' beats 'perfect before merge' for
pattern introductions.
2026-04-30 11:12:07 -07:00
Rodin ea9fa61d1e docs: pattern break archaeology — WHY (not just WHAT) is impure
Git blame + commit messages reveal four categories:
1. Ship behavior, fix plumbing later (time pressure)
2. Better tooling exposed limitations (observability)
3. Removal cost > carrying cost (zero-interest debt)
4. Context needs different patterns (not actually a break)

Specific findings:
- CockroachDB Handle: introduced for profiling, not correctness
- Stale 22.2 TODO: struct field costs 0, removal touches many files
- Prometheus globals: startup constants read in hot path = correct call
- AppenderV2: unifies 4 type-asserted interfaces into 1
- Ecto zero TODOs: version-gated, cleaned on version bumps by José
2026-04-30 11:07:12 -07:00
Rodin 9961f939c5 docs: pattern purity and codebase evolution analysis
How pure are these codebases? When do they break their own
conventions and why? Key finding: purity inversely correlates
with size. Ecto has 0 TODOs; CockroachDB has 1,048.
Neither is wrong — they're different kinds of systems.
2026-04-30 10:56:15 -07:00
Rodin 76f4bcc33e docs: architectural analysis of top repos (CockroachDB, Prometheus, Ecto, Oban)
Four documents examining codebases at module and ecosystem levels:
- architectural-analysis.md — internal structure, dependency flow
- ecosystem-analysis.md — consumer extension points, deliberate absences
- crosscutting-analysis.md — logging, config, retry, lifecycle
- testing-evolution-analysis.md — proof models, API evolution strategies
2026-04-30 10:50:54 -07:00
Rodin 22e103ebfb docs: Elixir patterns vs official guidelines with code examples + hypotheses 2026-04-30 07:58:31 -07:00
Rodin 6c1fa35b1c docs: enhance Go divergence analysis with code examples + hypotheses 2026-04-30 07:57:37 -07:00
Rodin ca07514d9c docs: Go patterns vs official guidelines divergence analysis 2026-04-30 07:50:32 -07:00