Define taxonomy: patterns vs conventions #4

New Issue

2026-05-08T00:59:37Z

rodin commented

2026-05-08 00:59:37 +00:00

Definitions

Pattern = prescriptive, reusable solution to a recurring problem. "When you face X, do Y." Language-scoped. Has When-to-Use, When-Not-to-Use, and Why. These are what you follow.

Convention = descriptive reference material showing how a specific project/framework structures things. Study for ideas, don't copy blindly. Applying the wrong framework's conventions to your codebase causes active harm.

Pattern repos (prescriptive — follow these)

elixir-patterns — how to write Elixir
go-patterns — how to write Go
rust-patterns — how to write Rust

Convention repos (reference — study, don't copy)

kubernetes-conventions — system architecture at scale
cockroachdb-conventions — distributed system architecture
phoenix-conventions — web framework opinions (don't apply to non-Phoenix code)
ecto-conventions — data layer opinions (don't apply to non-Ecto code)
temporal-conventions — workflow engine patterns

Fold into language patterns (too thin to be standalone)

oban-conventions → merge into elixir-patterns as source citations
prometheus-conventions → merge into go-patterns as source citations

Delete or archive (duplicates of patterns repos)

elixir-conventions — merge any unique content into elixir-patterns, then archive
golang-conventions — merge any unique content into go-patterns, then archive

Key principle

"Use it for ideas; don't get tempted to do something just because Phoenix does it."

Conventions are a reference to understand why a project made certain choices. Not a template to follow. Your context is different from theirs.

Actions

Add a README or top-level doc to each repo clarifying which category it is
Merge thin convention repos into corresponding pattern repos
Archive duplicates
Update patterns-vs-guidelines repo with this taxonomy

## Definitions **Pattern** = prescriptive, reusable solution to a recurring problem. "When you face X, do Y." Language-scoped. Has When-to-Use, When-Not-to-Use, and Why. These are what you follow. **Convention** = descriptive reference material showing how a specific project/framework structures things. Study for ideas, don't copy blindly. Applying the wrong framework's conventions to your codebase causes active harm. ## Pattern repos (prescriptive — follow these) - `elixir-patterns` — how to write Elixir - `go-patterns` — how to write Go - `rust-patterns` — how to write Rust ## Convention repos (reference — study, don't copy) - `kubernetes-conventions` — system architecture at scale - `cockroachdb-conventions` — distributed system architecture - `phoenix-conventions` — web framework opinions (don't apply to non-Phoenix code) - `ecto-conventions` — data layer opinions (don't apply to non-Ecto code) - `temporal-conventions` — workflow engine patterns ## Fold into language patterns (too thin to be standalone) - `oban-conventions` → merge into `elixir-patterns` as source citations - `prometheus-conventions` → merge into `go-patterns` as source citations ## Delete or archive (duplicates of patterns repos) - `elixir-conventions` — merge any unique content into `elixir-patterns`, then archive - `golang-conventions` — merge any unique content into `go-patterns`, then archive ## Key principle "Use it for ideas; don't get tempted to do something just because Phoenix does it." Conventions are a reference to understand *why* a project made certain choices. Not a template to follow. Your context is different from theirs. ## Actions 1. Add a README or top-level doc to each repo clarifying which category it is 2. Merge thin convention repos into corresponding pattern repos 3. Archive duplicates 4. Update `patterns-vs-guidelines` repo with this taxonomy

rodin commented

2026-05-08 00:59:45 +00:00

Cleanup tasks (file as individual issues or handle during free time)

Audit elixir-conventions — extract anything unique into elixir-patterns, archive the repo
Audit golang-conventions — extract anything unique into go-patterns, archive the repo
Merge oban-conventions content into elixir-patterns as source citations, archive
Merge prometheus-conventions into go-patterns as source citations, archive
Add README header to each surviving convention repo: "Reference material. Study for ideas, don't copy."
Add README header to each pattern repo: "Prescriptive. Follow these."
Update MEMORY.md to reference the taxonomy
Evaluate patterns-vs-guidelines repo — does it still serve a purpose with clear taxonomy?

## Cleanup tasks (file as individual issues or handle during free time) - [ ] Audit `elixir-conventions` — extract anything unique into `elixir-patterns`, archive the repo - [ ] Audit `golang-conventions` — extract anything unique into `go-patterns`, archive the repo - [ ] Merge `oban-conventions` content into `elixir-patterns` as source citations, archive - [ ] Merge `prometheus-conventions` into `go-patterns` as source citations, archive - [ ] Add README header to each surviving convention repo: "Reference material. Study for ideas, don't copy." - [ ] Add README header to each pattern repo: "Prescriptive. Follow these." - [ ] Update MEMORY.md to reference the taxonomy - [ ] Evaluate `patterns-vs-guidelines` repo — does it still serve a purpose with clear taxonomy?

rodin referenced this issue from a commit

2026-05-08 01:01:39 +00:00

chore: merge elixir-conventions and oban-conventions into sources/

rodin referenced this issue from a commit

2026-05-08 01:01:48 +00:00

chore: merge elixir-conventions and oban-conventions into sources/

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: rodin/elixir-patterns#4