Skip to content

Commit 3ff1fa6

Browse files
alexeygrigorevalexeygrigorev
committed
Merge issue #93 development terminology
2 parents f95ef16 + f79f788 commit 3ff1fa6

39 files changed

Lines changed: 2724 additions & 1657 deletions

‎.github/workflows/ci.yml‎

Lines changed: 214 additions & 256 deletions
Large diffs are not rendered by default.

‎Makefile‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
test-core test test-compatibility compatibility-source-artifacts-check \
33
compatibility-artifacts-check check-links check-seo compatibility-real-gate-blocked-check \
44
test-content test-content-postgresql test-playwright-core test-playwright migrate run worker \
5-
terraform-seo-source-check check-openapi check-management-parity
5+
terraform-seo-source-check terminology-check check-openapi check-management-parity
66

77
ADOPTION_INTEGRATION_PYTHON = \
88
accounts/managers.py \
@@ -49,6 +49,9 @@ django-check: check-openapi check-management-parity
4949
deployment-check:
5050
DTC_ENVIRONMENT=production DJANGO_SETTINGS_MODULE=website.settings.production DJANGO_SECRET_KEY="$$(uv run python -c 'import secrets; print(secrets.token_urlsafe(64))')" DATABASE_URL=postgresql://check:check@127.0.0.1:5432/check DJANGO_ALLOWED_HOSTS=example.invalid DJANGO_CSRF_TRUSTED_ORIGINS=https://example.invalid uv run python manage.py check --deploy --fail-level ERROR
5151

52+
terminology-check:
53+
uv run python scripts/check_development_terminology.py
54+
5255
terraform-seo-source-check:
5356
@test -n "$(AWS_INFRA_REPOSITORY)" || (echo "AWS_INFRA_REPOSITORY is required" >&2; exit 2)
5457
@test -n "$(AWS_INFRA_REVISION)" || (echo "AWS_INFRA_REVISION is required" >&2; exit 2)

‎_docs/compatibility/development-legacy-identifiers.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
# Development legacy-identifier boundary
2+
3+
`web.dtcdev.click` is the development environment. `sandbox` was its former
4+
repository-facing name. Issue [#93](https://github.com/DataTalksClub/website/issues/93)
5+
changes current application, workflow, API, test, and operator terminology to
6+
development. Issue [#94](https://github.com/DataTalksClub/website/issues/94)
7+
owns any later state-safe physical infrastructure and OIDC-trust rename.
8+
9+
## Live compatibility identifiers
10+
11+
The following values still identify the same live development deployment and
12+
must remain byte-exact until #94:
13+
14+
- Terraform root/state prefix `sandbox/website`, including its state key and lock;
15+
- state bucket `datamailer-sandbox-817685572750-us-east-1-tfstate`;
16+
- physical `website-sandbox*` AWS resources, ARNs, secret paths, log groups, and KMS alias;
17+
- GitHub environment `sandbox` and the OIDC subject ending in `environment:sandbox`;
18+
- physical resource-tag value `Environment=sandbox`; and
19+
- bootstrap role/session identifiers `phone-aws-sandbox-role` and `phone-sandbox-*`.
20+
21+
Current Python code consumes these values through
22+
`deploy/legacy_development_compatibility.py`. The workflow reads only
23+
`DEVELOPMENT_*` GitHub variables; its four exact GitHub-environment bindings
24+
remain literal compatibility declarations because GitHub resolves them before
25+
any checked-out code can run. No Terraform, state, AWS resource, tag, IAM,
26+
GitHub-environment, or OIDC-trust mutation is part of #93.
27+
28+
## Frozen evidence
29+
30+
The following classes retain their original bytes and wording. Readers may
31+
label them legacy evidence but must not rewrite or regenerate them:
32+
33+
- timestamped reports in `_docs/audits/`;
34+
- captured inventories in `_docs/compatibility/*.jsonl`;
35+
- `deploy/gate_b_binding_seed.json`, `deploy/gate_b_execution_contract.json`,
36+
`deploy/gate_b_manifest.json`, and their hash-bound evidence reader/tests;
37+
- prior Actions runs, artifacts, release records, task-definition ARNs, SHAs,
38+
issue evidence, and Git history; and
39+
- the Gate-B assembler/operator and OIDC probe adapters that verify those exact
40+
historical schemas and source hashes.
41+
42+
The old specification and runbook paths remain only as small link notices.
43+
Canonical operator material is in
44+
[`08-aws-development-terraform.md`](../specs/08-aws-development-terraform.md)
45+
and [`development-release.md`](../runbooks/development-release.md).

‎_docs/compatibility/development-terminology-allowlist.json‎

Lines changed: 232 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,232 @@
1+
{
2+
"version": 1,
3+
"self_reason": "This inventory necessarily spells the former name in regexes; the checker parses but does not scan this policy file.",
4+
"legacy_paths": [
5+
{
6+
"path": "_docs/runbooks/sandbox-release.md",
7+
"class": "legacy_path",
8+
"reason": "Small compatibility notice preserves inbound links to the former runbook path.",
9+
"follow_up": "#94",
10+
"expected_count": 1
11+
},
12+
{
13+
"path": "_docs/specs/08-aws-sandbox-terraform.md",
14+
"class": "legacy_path",
15+
"reason": "Small compatibility notice preserves inbound links to the former specification path.",
16+
"follow_up": "#94",
17+
"expected_count": 1
18+
}
19+
],
20+
"whole_files": [
21+
{
22+
"path": "_docs/audits/2026-08-07-oidc-denial-sentinels.md",
23+
"sha256": "8c4e9b6701d670bac87853254d66b2399e379e79b072409690c68acb3a3e9696",
24+
"class": "frozen_historical",
25+
"reason": "Timestamped OIDC denial audit retains its exact historical wording.",
26+
"follow_up": "none; immutable evidence",
27+
"expected_count": 8
28+
},
29+
{
30+
"path": "_docs/audits/2026-08-08-gate-b-operator-execution.md",
31+
"sha256": "1c2c231e401e630a2907fd8bbc75d06c25ec7e1059646a95bd584810244afe6f",
32+
"class": "frozen_historical",
33+
"reason": "Timestamped Gate-B execution audit retains its exact historical wording.",
34+
"follow_up": "none; immutable evidence",
35+
"expected_count": 4
36+
},
37+
{
38+
"path": "_docs/compatibility/faq-fragment-contracts.jsonl",
39+
"sha256": "489ca0db5fd87406d27841748a0dfb8d9ec43bfb2a029ee054335871f625e37c",
40+
"class": "captured_compatibility",
41+
"reason": "Captured FAQ compatibility data retains source bytes.",
42+
"follow_up": "none; immutable capture",
43+
"expected_count": 1
44+
},
45+
{
46+
"path": "_docs/compatibility/legacy-manifest.jsonl",
47+
"sha256": "94a6469530a290147e94f825eb981836e1358b9d0a72c7f50f0eda6d638e1d7f",
48+
"class": "captured_compatibility",
49+
"reason": "Captured public-route inventory retains source bytes.",
50+
"follow_up": "none; immutable capture",
51+
"expected_count": 8
52+
},
53+
{
54+
"path": "_docs/compatibility/public-contracts.jsonl",
55+
"sha256": "50f875806217865ef35b74f58ed885c4b5c832284391dbea7f84344d3416f66d",
56+
"class": "captured_compatibility",
57+
"reason": "Captured public-contract inventory retains source bytes.",
58+
"follow_up": "none; immutable capture",
59+
"expected_count": 2
60+
},
61+
{
62+
"path": "deploy/gate_b_binding_seed.json",
63+
"sha256": "6a32cfabcad8c3cf18d5de8d46b30d970f8e85dd0a65a0cac700762eb4b6f52b",
64+
"class": "frozen_historical",
65+
"reason": "Pinned Gate-B binding seed is hash-bound immutable evidence.",
66+
"follow_up": "none; immutable evidence",
67+
"expected_count": 61
68+
},
69+
{
70+
"path": "deploy/gate_b_execution_contract.json",
71+
"sha256": "8cf5b62e78ee617d46c1338452caf493cd60e1ffa93169c2a026feab6d300342",
72+
"class": "frozen_historical",
73+
"reason": "Pinned Gate-B execution contract is hash-bound immutable evidence.",
74+
"follow_up": "none; immutable evidence",
75+
"expected_count": 195
76+
},
77+
{
78+
"path": "deploy/gate_b_manifest.json",
79+
"sha256": "c96f710091adfc0e9c85ed02329238f374118766f46f630ea956794015987985",
80+
"class": "frozen_historical",
81+
"reason": "Pinned Gate-B manifest is hash-bound immutable evidence.",
82+
"follow_up": "none; immutable evidence",
83+
"expected_count": 168
84+
},
85+
{
86+
"path": "deploy/gate_b_evidence.py",
87+
"sha256": "52d93e9b2757c75c4ec633ac2d903fdce658b107481382025c22bf0f9d276b68",
88+
"class": "frozen_historical",
89+
"reason": "Gate-B evidence reader source is hash-bound by the frozen contract.",
90+
"follow_up": "none; immutable evidence",
91+
"expected_count": 45
92+
},
93+
{
94+
"path": "core/tests/test_gate_b_evidence.py",
95+
"sha256": "4dd65a576f3bd3d3bd2dff41170ee161f45ffe5362a4e4e1f8af0feabc081027",
96+
"class": "frozen_historical",
97+
"reason": "Gate-B evidence tests are hash-bound by the frozen contract.",
98+
"follow_up": "none; immutable evidence",
99+
"expected_count": 71
100+
},
101+
{
102+
"path": "deploy/oidc_probe.py",
103+
"sha256": "10f38b3c3df04c763f0e09ffe6128fc9d9fe174c4f3f7f161600992fcd84e2ff",
104+
"class": "legacy_schema_reader",
105+
"reason": "Hash-bound OIDC probe remains the exact legacy-identifier adapter behind a development entry point.",
106+
"follow_up": "#94",
107+
"expected_count": 21
108+
},
109+
{
110+
"path": "deploy/oidc_claim_probe.py",
111+
"sha256": "693b1844e5e1c40709ce368ecb6bef22814a5912ceaa635288f0d0204a75ba28",
112+
"class": "legacy_schema_reader",
113+
"reason": "Hash-bound wrong-claim probe retains exact physical role patterns.",
114+
"follow_up": "#94",
115+
"expected_count": 1
116+
},
117+
{
118+
"path": "core/tests/test_deployment_oidc_probe.py",
119+
"sha256": "58b447bc72ddfd11359f801087ba5a2f896f0d56bff7a832c6a2768d34f74b92",
120+
"class": "legacy_contract_test",
121+
"reason": "Hash-bound probe tests prove exact legacy evidence and physical values remain readable.",
122+
"follow_up": "#94",
123+
"expected_count": 30
124+
},
125+
{
126+
"path": "deploy/gate_b_assembler.py",
127+
"sha256": "f3d7a431b1cba8e9eb12e1a511f60beb5b70d0d14560d3df4f5428e42f3ad7f7",
128+
"class": "legacy_schema_reader",
129+
"reason": "Gate-B assembler reads the pinned legacy schema without rewriting it.",
130+
"follow_up": "#94",
131+
"expected_count": 18
132+
},
133+
{
134+
"path": "deploy/gate_b_operator.py",
135+
"sha256": "487d7266022d4c36b48d0891e8821b0c55d0b0c81062c14c54d69085eba01a33",
136+
"class": "legacy_schema_reader",
137+
"reason": "Gate-B operator reads exact historical bindings and physical identifiers.",
138+
"follow_up": "#94",
139+
"expected_count": 3
140+
},
141+
{
142+
"path": "core/tests/test_gate_b_operator.py",
143+
"sha256": "f4de8251fe38e0595e246fa5db6ba63914bb5a7f788c6ba0fd171587edb624a2",
144+
"class": "legacy_contract_test",
145+
"reason": "Gate-B operator tests prove exact historical bindings remain readable.",
146+
"follow_up": "#94",
147+
"expected_count": 35
148+
},
149+
{
150+
"path": "_docs/compatibility/development-legacy-identifiers.md",
151+
"sha256": "7b6e30853e867c925069a393cb16720c047462684422825cc039cf6a5e37c142",
152+
"class": "compatibility_note",
153+
"reason": "Evergreen note explicitly documents former terminology and every retained identifier class.",
154+
"follow_up": "#94",
155+
"expected_count": 9
156+
},
157+
{
158+
"path": "deploy/legacy_development_compatibility.py",
159+
"sha256": "097ebbccb9e44909cfbda6de61176b0a9f19f6df50cf8cbf5aa808895e23bd31",
160+
"class": "legacy_physical_boundary",
161+
"reason": "Single executable boundary owns exact live physical identifiers for development.",
162+
"follow_up": "#94",
163+
"expected_count": 5
164+
},
165+
{
166+
"path": "_docs/runbooks/sandbox-release.md",
167+
"sha256": "163beb97eb7b508ecaa456d023b1a5620c54db8504557d4d6fa473294d9d61cb",
168+
"class": "legacy_link_notice",
169+
"reason": "Small command-free notice preserves the former runbook link.",
170+
"follow_up": "#94",
171+
"expected_count": 1
172+
},
173+
{
174+
"path": "_docs/specs/08-aws-sandbox-terraform.md",
175+
"sha256": "c0ae69b792e73d0a7d4f14222b25bc529b1c994ddcfa7e4d60951a5fff44e38d",
176+
"class": "legacy_link_notice",
177+
"reason": "Small non-normative notice preserves the former specification link.",
178+
"follow_up": "#94",
179+
"expected_count": 1
180+
},
181+
{
182+
"path": "core/tests/test_deployment_release.py",
183+
"sha256": "bf7b7650e4396c821fab95753b34baff1cf81ee819a2001fa7bb5cacf45fceb4",
184+
"class": "legacy_contract_test",
185+
"reason": "Release tests exercise exact physical task, secret, repository, and tag values.",
186+
"follow_up": "#94",
187+
"expected_count": 5
188+
},
189+
{
190+
"path": "core/tests/test_deployment_workflow.py",
191+
"sha256": "1cbc06f7733b1b0c252b0d4e3c8289669c15616c4b2007d5a325e5e6fc17618a",
192+
"class": "legacy_contract_test",
193+
"reason": "Workflow tests exercise removed inputs, frozen Gate-B records, and exact physical values.",
194+
"follow_up": "#94",
195+
"expected_count": 27
196+
}
197+
],
198+
"rules": [
199+
{
200+
"path": ".github/workflows/ci.yml",
201+
"pattern": "name:\\s+sandbox",
202+
"class": "legacy_physical_identifier",
203+
"reason": "Four jobs must retain the exact GitHub environment name and OIDC subject until trust migration.",
204+
"follow_up": "#94",
205+
"expected_count": 4
206+
},
207+
{
208+
"path": "_docs/runbooks/development-release.md",
209+
"pattern": "(?:sandbox/website|website-sandbox|datamailer-sandbox|phone-aws-sandbox|phone-sandbox|github-sandbox|environments/sandbox|--env sandbox|environment: sandbox|Environment=sandbox|`sandbox`)",
210+
"class": "legacy_physical_identifier",
211+
"reason": "Canonical runbook documents exact live physical identifiers and the legacy GitHub environment.",
212+
"follow_up": "#94",
213+
"expected_count": 88
214+
},
215+
{
216+
"path": "_docs/specs/08-aws-development-terraform.md",
217+
"pattern": "(?:sandbox/|website-sandbox)",
218+
"class": "legacy_physical_identifier",
219+
"reason": "Canonical specification names the unchanged Terraform root and AWS namespace.",
220+
"follow_up": "#94",
221+
"expected_count": 4
222+
},
223+
{
224+
"path": "_docs/specs/09-migration-rollout-roadmap.md",
225+
"pattern": "sandbox/website",
226+
"class": "legacy_physical_identifier",
227+
"reason": "Roadmap references the existing Terraform root without renaming state.",
228+
"follow_up": "#94",
229+
"expected_count": 1
230+
}
231+
]
232+
}

‎_docs/planning/critique.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -47,7 +47,7 @@ The plan has not been approved by the owner. The draft asks the owner to accept
4747
4. Which production sender/reply-to identities and delivery provider should be used after the Datamailer transition?
4848
5. What privacy contact, minors policy, educational-record retention, deletion/anonymization, SLO, RPO, and RTO apply?
4949
6. Is `Europe/Berlin` correct for legacy naive timestamps?
50-
7. Are the recommended no-NAT sandbox network and PostgreSQL Podwiki search acceptable subject to parity tests?
50+
7. Are the recommended no-NAT development network and PostgreSQL Podwiki search acceptable subject to parity tests?
5151

5252
Recommended defaults are written into the specifications so implementation can proceed predictably after approval, but they are not recorded as human decisions yet.
5353

0 commit comments

Comments
 (0)