Skip to content

Commit ed61054

Browse files
committed
feat(tools): stable entry ids and the reviewed open pull requests
Give every entry an id, a kind, and review dates. Check internal links and relationship refs. Land the open fixes that were still worth keeping. Deferred queue rows no longer count as duplicate collisions. Required sections ignore headings inside code fences. Family names are checked in both directions. Catalogue staleness uses one git log. Code samples compile in a thread pool. Section extraction stops at the next heading. The Fail Fast citation points at the IEEE Software PDF. Action pins move to the current checkout, setup-java, setup-python, and setup-node releases. Validator tests run from make and from CI.
1 parent 53a08de commit ed61054

961 files changed

Lines changed: 30349 additions & 1541 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/CONTRIBUTING.md‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -31,22 +31,24 @@ first. Rebase onto a different, unclaimed entry from the queue instead.
3131
`patterns/<family>/README.md` so a new entry does not duplicate one
3232
already published or already queued. Also check `gh pr list` for a draft
3333
PR already claiming the same path.
34-
3. Run the local gates before you push, the same four gates CI runs:
34+
3. Run the local gates before you push, the same gates CI runs:
3535

3636
```
3737
python3 tools/check-structure.py
3838
python3 tools/check-prose.py
39+
python3 tools/check-links.py
3940
python3 tools/check-code.py --strict
4041
python3 tools/validate-refs.py --strict
41-
npx --yes markdownlint-cli2@0.23.2 "patterns/**/*.md" "docs/**/*.md" README.md
42+
npx --yes markdownlint-cli2@0.23.2 "patterns/**/*.md" "docs/**/*.md" README.md GOVERNANCE.md MAINTAINERS.md
4243
```
4344

44-
4. If you touch `docs/AUTHORING-QUEUE.json` or add a published entry, also
45-
run `python3 tools/gen-indexes.py` and
46-
`python3 tools/gen-catalogue-status.py`, and commit the files they
47-
regenerate (family `README.md`, `docs/PROGRESS.md`, `dist/`, the root
48-
`README.md` badges and table) in the same commit. A stale catalogue status
49-
is caught in CI and blocks the merge.
45+
4. If you touch `docs/AUTHORING-QUEUE.json`, add a published entry, or change
46+
frontmatter relationships, also run `python3 tools/gen-indexes.py`,
47+
`python3 tools/gen-catalogue-status.py`, and
48+
`python3 tools/gen-entry-index.py`. Commit the files they regenerate
49+
(family `README.md`, `docs/PROGRESS.md`, `dist/`, the root `README.md`
50+
badges and table) in the same commit. A stale catalogue status or entry
51+
index is caught in CI and blocks the merge.
5052

5153
## What a pull request needs
5254

@@ -96,5 +98,5 @@ discusses those exact strings.
9698
## License
9799

98100
By contributing, you agree your contribution is licensed under this
99-
repository's OpenRoots Agent License 1.0 (see `LICENSE`), and that you have
101+
repository's OpenRoots Agent License 2.3 (see `LICENSE`), and that you have
100102
the right to license it that way.

‎.github/workflows/ci.yml‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -19,19 +19,27 @@ jobs:
1919
runs-on: ubuntu-latest
2020
steps:
2121
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
22-
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
22+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
2323
with:
2424
python-version: "3.12"
2525
- name: Structural validator tests
2626
run: python3 tools/check-structure-test.py
27+
- name: Link and identity tests
28+
run: python3 tools/check-links-test.py
29+
- name: Internal links and entry identity
30+
run: python3 tools/check-links.py
2731
- name: Structural gate
2832
run: python3 tools/check-structure.py
2933
- name: Family naming validator tests
3034
run: python3 tools/check-family-names-test.py
3135
- name: Family folder naming gate
3236
run: python3 tools/check-family-names.py
37+
- name: Prose validator tests
38+
run: python3 tools/check-prose-test.py
3339
- name: Prose gate
3440
run: python3 tools/check-prose.py
41+
- name: Family index generator tests
42+
run: python3 tools/gen-indexes-test.py
3543
- name: Indexes are current
3644
run: |
3745
python3 tools/gen-indexes.py
@@ -53,31 +61,44 @@ jobs:
5361
- name: Catalogue status is current
5462
run: |
5563
python3 tools/gen-catalogue-status.py
56-
git diff --exit-code -- README.md docs/PROGRESS.md dist/ || {
64+
git diff --exit-code -- README.md docs/PROGRESS.md dist/catalogue-status.json dist/catalogue-status.csv || {
5765
echo "Catalogue status is stale. Run tools/gen-catalogue-status.py and commit."
5866
exit 1
5967
}
68+
- name: Entry index is current
69+
run: |
70+
python3 tools/gen-entry-index.py
71+
git ls-files --error-unmatch dist/entries.json >/dev/null || {
72+
echo "dist/entries.json is not tracked. Run tools/gen-entry-index.py and commit it."
73+
exit 1
74+
}
75+
git diff --exit-code -- dist/entries.json || {
76+
echo "Entry index is stale. Run tools/gen-entry-index.py and commit."
77+
exit 1
78+
}
6079
6180
code:
6281
name: code samples compile
6382
runs-on: ubuntu-latest
6483
steps:
6584
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
66-
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
85+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
6786
with:
6887
python-version: "3.12"
69-
- uses: actions/setup-java@b6effb05e454b25005698d916606bdc6ffcbf961 # v5.7.0
88+
- uses: actions/setup-java@77dd5b2ce225ea11469928ac317850245a74ae78 # v6.2.0
7089
with:
7190
distribution: temurin
7291
java-version: "21"
7392
- uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7.0.0
7493
with:
7594
go-version: "1.23"
76-
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
95+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
7796
with:
7897
node-version: "22"
7998
- name: Rust toolchain
8099
run: rustup toolchain install stable --profile minimal --no-self-update
100+
- name: Code validator tests
101+
run: python3 tools/check-code-test.py
81102
- name: Compile every sample
82103
run: python3 tools/check-code.py --strict
83104

@@ -86,7 +107,7 @@ jobs:
86107
runs-on: ubuntu-latest
87108
steps:
88109
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
89-
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
110+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
90111
with:
91112
python-version: "3.12"
92113
- name: Probe every cited URL
@@ -97,7 +118,7 @@ jobs:
97118
runs-on: ubuntu-latest
98119
steps:
99120
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
100-
- uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
121+
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
101122
with:
102123
node-version: "22"
103124
- name: markdownlint-cli2
@@ -112,11 +133,13 @@ jobs:
112133
pull-requests: read
113134
steps:
114135
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
115-
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
136+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
116137
with:
117138
python-version: "3.12"
118139
- name: Fetch main for comparison
119140
run: git fetch origin main --depth=200
141+
- name: Claim check validator tests
142+
run: python3 tools/check-claims-test.py
120143
- name: No two contributors on the same entry
121144
env:
122145
GH_TOKEN: ${{ github.token }}
@@ -135,7 +158,7 @@ jobs:
135158
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
136159
with:
137160
fetch-depth: 0
138-
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
161+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
139162
with:
140163
python-version: "3.12"
141164
- name: Install gitleaks

‎.github/workflows/no-ai-attribution.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,7 +12,7 @@ jobs:
1212
check:
1313
runs-on: ubuntu-latest
1414
steps:
15-
- uses: actions/checkout@08eba0b27e820071cde6df949e0beb9ba4906955 # v4.3.0
15+
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
1616
with:
1717
fetch-depth: 0
1818
- name: Reject AI authors and attribution lines

‎.github/workflows/refresh-citations.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@ jobs:
1414
runs-on: ubuntu-latest
1515
steps:
1616
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
17-
- uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
17+
- uses: actions/setup-python@6d4fd22b20465ccc0f7354476588e8df7c9ca0e0 # v7.1.0
1818
with:
1919
python-version: "3.12"
2020
- name: Probe every citation fresh, report only

‎.markdownlint-cli2.jsonc‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,6 @@
1313
"MD041": false,
1414
"MD060": false
1515
},
16-
"globs": ["patterns/**/*.md", "docs/**/*.md", "README.md"],
16+
"globs": ["patterns/**/*.md", "docs/**/*.md", "README.md", "GOVERNANCE.md", "MAINTAINERS.md"],
1717
"ignores": ["docs/council/**"]
1818
}

‎.ref-cache.json‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3345,6 +3345,7 @@
33453345
"https://martinfowler.com/eaaDev/SupervisingPresenter.html": 200,
33463346
"https://martinfowler.com/eaaDev/uiArchs.html": 200,
33473347
"https://martinfowler.com/ieeeSoftware/coupling.pdf": 200,
3348+
"https://martinfowler.com/ieeeSoftware/failFast.pdf": 200,
33483349
"https://martinfowler.com/ieeeSoftware/protectedVariation.pdf": 200,
33493350
"https://martinfowler.com/refactoringErrata.html": 200,
33503351
"https://masstransit.io/documentation/concepts/messages": 200,
@@ -5067,4 +5068,4 @@
50675068
"https://zipkin.io/pages/architecture.html": 200,
50685069
"https://zookeeper.apache.org/doc/current/recipes.html": 200,
50695070
"https://zookeeper.apache.org/doc/current/zookeeperProgrammers.html": 200
5070-
}
5071+
}

‎ATTRIBUTION.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -176,4 +176,4 @@ content will be reviewed and corrected or removed promptly.
176176
## Contributing attribution
177177

178178
Contributors agree that their contribution is original and is licensed under
179-
this repository's OpenRoots Agent License 1.0. See `.github/CONTRIBUTING.md`.
179+
this repository's OpenRoots Agent License 2.3. See `.github/CONTRIBUTING.md`.

‎GOVERNANCE.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Governance
2+
3+
This catalogue has one maintainer. [MAINTAINERS.md](MAINTAINERS.md) names
4+
that person. `.github/CODEOWNERS` gives them every path until a family has
5+
its own reviewer.
6+
7+
## What a maintainer decides
8+
9+
- Whether an entry's `maturity` is `canonical`, `established`, `emerging`,
10+
`contested`, or `deprecated`.
11+
- Whether a proposed pattern is a real, citable pattern or a rename of one
12+
already published. `docs/CATALOG-COMPARISON.md` records the comparisons
13+
already made. A new family is a scope decision. Open a `new-pattern` issue
14+
before adding the family. Do not invent entries to close a numeric gap.
15+
- Whether a deferred queue row in `docs/AUTHORING-QUEUE.json` may be
16+
authored. The three deferred rows say why they stay deferred. Do not
17+
author them from a guess.
18+
- Disputes about a published claim. Use the matching issue template under
19+
`.github/ISSUE_TEMPLATE/`. A correction lands as a pull request that
20+
passes the same gates as a new entry.
21+
22+
## What the tools decide
23+
24+
`tools/check-structure.py` checks the eighteen dimensions.
25+
`tools/check-prose.py` checks prose shape.
26+
`tools/check-code.py` compiles samples.
27+
`tools/validate-refs.py` checks that a cited URL answers.
28+
`tools/check-links.py` checks internal links, entry ids, kinds, review
29+
dates, and the relationship lists.
30+
`tools/check-duplicates.py` warns on name collisions.
31+
`tools/gen-catalogue-status.py` and `tools/gen-entry-index.py` regenerate
32+
the counts and `dist/entries.json`.
33+
34+
A URL that returns success is not proof the page supports the sentence
35+
beside it. That limit is stated in [docs/CITATION-POLICY.md](docs/CITATION-POLICY.md).
36+
No tool in this repository pretends to close it.
37+
38+
## Identity
39+
40+
Every entry carries an id of the form `pat.<family number>.<slug>`. Twelve slugs are
41+
published in more than one family. Those relationships use `family/slug`.
42+
A bare slug is allowed only when one file owns it.
43+
44+
`related` and `incompatible_with` are catalogue links.
45+
`related_concepts` and `incompatible_concepts` are names that are not
46+
published entries. Keeping them separate is how a typo becomes a failed
47+
check instead of a silent break.
48+
49+
## Review dates
50+
51+
`verified`, `last_reviewed`, and `next_review_due` are calendar dates.
52+
`last_reviewed` was filled from `verified` when those fields were added.
53+
`next_review_due` is 180 days after `last_reviewed` until someone who
54+
re-reads the entry sets a new date. The stale-entry count in the README
55+
still comes from git history, via `tools/gen-catalogue-status.py`, not
56+
from this date.
57+
58+
Eight release entries had `verified` set to the boolean true. Those dates were repaired
59+
from the commit date of the file. That is the only dated record those
60+
files had.
61+
62+
## License
63+
64+
Contributions are licensed under the OpenRoots Agent License 2.3. See
65+
`LICENSE` and `.github/CONTRIBUTING.md`.

‎MAINTAINERS.md‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
# Maintainers
2+
3+
| Name | GitHub | Scope |
4+
|---|---|---|
5+
| Mirza Iqbal | [@mjmirza](https://github.com/mjmirza) | Every path. See `.github/CODEOWNERS`. |
6+
7+
There is no second reviewer, and no family has a specialist owner yet.
8+
That is a real limit. CI checks structure, prose, code, citation liveness,
9+
and internal links. It does not check that a distributed-systems claim, a
10+
security claim, or a category-theory claim is right. Domain review is still
11+
one person.
12+
13+
A contributor becomes a family owner by a sustained run of correct
14+
corrections in that family, after which the maintainer edits
15+
`.github/CODEOWNERS` to name them on that directory. Opening a pull request
16+
does not grant that ownership.
17+
18+
Security reports follow `.github/SECURITY.md`.

‎Makefile‎

Lines changed: 19 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
1-
.PHONY: check structure refs prose code catalogue catalogue-check by-problem-by-language by-problem-by-language-check duplicates duplicates-test test all stats
1+
.PHONY: check structure refs prose code links catalogue catalogue-check by-problem-by-language by-problem-by-language-check entries entries-check duplicates duplicates-test test all stats
22

33
all: check
44

5-
check: test structure prose code refs catalogue-check by-problem-by-language-check duplicates-test
5+
check: test structure prose links code refs catalogue-check by-problem-by-language-check entries-check duplicates-test
66

77
structure:
88
@python3 tools/check-structure.py
@@ -13,14 +13,26 @@ refs:
1313
prose:
1414
@python3 tools/check-prose.py
1515

16+
links:
17+
@python3 tools/check-links.py
18+
19+
entries:
20+
@python3 tools/gen-entry-index.py
21+
22+
entries-check: entries
23+
@git ls-files --error-unmatch dist/entries.json >/dev/null || \
24+
(echo "dist/entries.json is not tracked. Run 'make entries' and commit it." && exit 1)
25+
@git diff --exit-code -- dist/entries.json || \
26+
(echo "Entry index is stale. Run 'make entries' and commit." && exit 1)
27+
1628
code:
1729
@python3 tools/check-code.py --strict
1830

1931
catalogue:
2032
@python3 tools/gen-catalogue-status.py
2133

2234
catalogue-check: catalogue
23-
@git diff --exit-code -- README.md docs/PROGRESS.md dist/ || \
35+
@git diff --exit-code -- README.md docs/PROGRESS.md dist/catalogue-status.json dist/catalogue-status.csv || \
2436
(echo "Catalogue status is stale. Run 'make catalogue' and commit." && exit 1)
2537

2638
by-problem-by-language:
@@ -32,6 +44,7 @@ by-problem-by-language-check: by-problem-by-language
3244

3345
test:
3446
@python3 tools/check-structure-test.py
47+
@python3 tools/check-links-test.py
3548
@python3 tools/check-family-names-test.py
3649
@python3 tools/check-prose-test.py
3750
@python3 tools/gen-indexes-test.py
@@ -40,6 +53,9 @@ test:
4053
@python3 tools/check-code-test.py
4154
@python3 tools/check-claims-test.py
4255
@python3 tools/next-batch-test.py
56+
@python3 tools/validate-refs-test.py
57+
@python3 tools/check-duplicates-test.py
58+
@python3 tools/check-pr-security-test.py
4359

4460
duplicates:
4561
@python3 tools/check-duplicates.py --strict

0 commit comments

Comments
 (0)