You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 4073968
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/decisions/050-what-stays-upstream.md
+8-5Lines changed: 8 additions & 5 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -48,8 +48,11 @@ every answer to those questions moves to forks.
48
48
upstream right for all of them, and each fork supplies its own answer.
49
49
- History-safety rules in git hold for every team; branch prefixes and title
50
50
forms are one team's choice.
51
-
- Recording decisions is documentation practice any team benefits from; only
52
-
a project's categories are its own.
51
+
- Which documents a project keeps, and how each is laid out, differ across
52
+
teams and organisations. Upstream requires only the documents every
53
+
project needs, `README.md`, `AGENTS.md` and `CLAUDE.md`, and prescribes
54
+
no document's structure, so the core stays as lean as the waist test
55
+
allows.
53
56
54
57
## Design
55
58
@@ -59,11 +62,11 @@ every answer to those questions moves to forks.
59
62
| - | ---- | ----------- |
60
63
| 1 | The waist test | A rule stays upstream only if changing the stack, the platform or the team's way of working would not change it |
61
64
| 2 | Engine upstream | The manifest schema, IDs, EXTEND and OVERRIDE, the resolver, `tools/`, `tests/`, and a fixture stack and platform as test input |
62
-
| 3 | Shared policy upstream |`core/`: config, oop, quality, testing, readme, the review checklists, and `agents.md` as the output contract; `security/`, `data/`, `infra/`, `backend/` and `frontend/`|
65
+
| 3 | Shared policy upstream |`core/`: config, oop, quality, testing, the review checklists, and `agents.md` as the output contract; `security/`, `data/`, `infra/`, `backend/` and `frontend/`|
63
66
| 4 | Rules, not language checks |`core/` states each idiom's rule language-neutrally and carries no language-specific code; the check moves with `language/`, which leaves upstream whole (#1926) |
64
67
| 5 | Governance asks, forks answer | Upstream asks who approves a change, how work is tracked and what a release is, and answers none of them. Labels, milestones, merge and review policy, the journal, wrap-up and the release cut move to forks |
65
68
| 6 | Git splits | Upstream keeps never force-push, never rebase a pushed branch, one concern per pull request, committer identity, submodules, off-limits paths and `.gitignore`. Branch prefixes, commit and title form, squash policy, versioning and the release process move |
66
-
| 7 |Decision records stay upstream|The ADR threshold, the record layout, the immutability rules and the schema and layout checks; a fork sets only its categories and the record its layout binds from|
69
+
| 7 |Required documents, no structure|Upstream requires `README.md`, `AGENTS.md` and `CLAUDE.md` and prescribes no document's structure. `core/readme.md`, decision records (threshold, layout, immutability, schema and layout checks), the changelog format, arc42, and the ONBOARDING, PLAYBOOK and journal rules move|
67
70
| 8 | Workflow moves | All of `workflow/` moves, `release.md` included. From `quality-gates.md`, how a check is built stays; when gates run moves: the three-layer gate model, thresholds and periodic audits |
68
71
| 9 | Ends move |`stack/`, `platform/`, `INTERVIEW.md`, `examples/`, `generated/`, `backend/templating.md`, `language/`, and `core/` cli, skills and examples |
69
72
| 10 | Concern directories | Upstream drops `base/`: `core/`, `security/`, `data/` and `infra/` sit beside `backend/` and `frontend/` under `templates/` (#1504) |
@@ -96,7 +99,7 @@ leaves it for the project or its fork to fill in:
96
99
| Keep the 2026-09-12 map, with the release rules and gate model upstream | The release cut and the gate schedule are one team's answers, and they would keep the file wrong for teams that work otherwise. |
97
100
| Keep governance upstream and let forks OVERRIDE it | Every fork inherits answers it must find and undo, and a missed one silently governs its projects. |
98
101
| Move the whole git policy to forks | The history-safety rules hold for every team, and a project with no fork would lose them. |
99
-
|Move decision records to forks | Every fork would rebuild the same threshold, layout and check. |
102
+
|Keep decision records and the README structure upstream | A record's layout and a README's sections are one organisation's structure; a fork that works otherwise would have to find and override them, and a lean core outweighs each fork keeping its own. |
100
103
| Split by whole file | Three files mix policy and process, so either half would land on the wrong side. |
101
104
| Fold each language check into `core/` beside its rule | A Python check changes with the stack, so it fails rule 1, and language code in `core/` grows every chain, the non-Python ones included. |
<mxCell id="u2" parent="1" style="rounded=1;arcSize=8;whiteSpace=wrap;html=1;fillColor=#FEF3C7;gradientColor=#FFFFFF;gradientDirection=north;strokeColor=#B45309;strokeWidth=1.6;shadow=1;align=center;fontFamily=Segoe UI;fontColor=#0F172A;spacing=6;" value="<b style='font-size:13px;color:#0F172A'>Language idioms, as rules</b><br><span style='font-size:11px;color:#92400E'>stated in core/ with no language code</span>" vertex="1"><mxGeometry x="60" y="302" width="630" height="62" as="geometry" /></mxCell>
14
14
<mxCell id="u3" parent="1" style="rounded=1;arcSize=8;whiteSpace=wrap;html=1;fillColor=#FEF3C7;gradientColor=#FFFFFF;gradientDirection=north;strokeColor=#B45309;strokeWidth=1.6;shadow=1;align=center;fontFamily=Segoe UI;fontColor=#0F172A;spacing=6;" value="<b style='font-size:13px;color:#0F172A'>Questions every project answers</b><br><span style='font-size:11px;color:#92400E'>who approves a change, how work is tracked,<br>what a release is</span>" vertex="1"><mxGeometry x="60" y="378" width="630" height="62" as="geometry" /></mxCell>
15
15
<mxCell id="u4" parent="1" style="rounded=1;arcSize=8;whiteSpace=wrap;html=1;fillColor=#FEF3C7;gradientColor=#FFFFFF;gradientDirection=north;strokeColor=#B45309;strokeWidth=1.6;shadow=1;align=center;fontFamily=Segoe UI;fontColor=#0F172A;spacing=6;dashed=1;dashPattern=6 4;" value="<b style='font-size:13px;color:#0F172A'>git.md: safety</b><br><span style='font-size:11px;color:#92400E'>never force-push, never rebase a pushed branch,<br>one concern per pull request</span>" vertex="1"><mxGeometry x="60" y="454" width="630" height="62" as="geometry" /></mxCell>
<mxCell id="u6" parent="1" style="rounded=1;arcSize=8;whiteSpace=wrap;html=1;fillColor=#FEF3C7;gradientColor=#FFFFFF;gradientDirection=north;strokeColor=#B45309;strokeWidth=1.6;shadow=1;align=center;fontFamily=Segoe UI;fontColor=#0F172A;spacing=6;dashed=1;dashPattern=6 4;" value="<b style='font-size:13px;color:#0F172A'>quality-gates.md: building a check</b><br><span style='font-size:11px;color:#92400E'>freeze instances, pair a constraint with its check,<br>run the check in the form it ships</span>" vertex="1"><mxGeometry x="60" y="606" width="630" height="62" as="geometry" /></mxCell>
<mxCell id="t3" parent="1" style="text;html=1;whiteSpace=wrap;strokeColor=none;fillColor=none;align=left;verticalAlign=top;fontFamily=Segoe UI;fontSize=12;fontColor=#475569;" value="IDs do not change: a template or section that moves keeps its ID, so a fork's EXTEND and OVERRIDE directives still resolve." vertex="1"><mxGeometry x="30" y="712" width="1380" height="24" as="geometry" /></mxCell>
0 commit comments