docs: take one site's name, hosts and paths off the public wiki
The publishability gate caught internal tooling names and developer paths but nothing site-specific, so roughly sixty leaks reached the wiki: the site name in ten documents, real fleet hostnames in the collector and GE-Enforce examples, an internal database name through the whole import guide, imaging-share paths, and a maintainer's username as the Deciders line of every ADR and inside a generated curl example. None of it is a security matter on an air-gapped fleet. It matters because these pages are read by engineers at other plants, and a document that names one site throughout reads as that site's notes rather than a product's documentation - which is exactly what it then gets treated as. Examples now use neutral hostnames, the site is "the reference site" where the distinction carries meaning, and ADRs are decided by "ShopDB maintainers". The gate carries all of these patterns, so the next one fails a build. Two documents leave docs/ because they were never written for an outside reader. PROJECT-REVIEW.md is an internal health memo pinned to a commit from July, whose headline finding (an untracked playbook) has since been fixed - it is history, and git holds it. PILOT-DEPLOY.md is one site's own cutover runbook, complete with a "re-measure before publishing" placeholder; it moves next to the loader it belongs to, in scripts/site_imports/wjf/. ADR-015 is AMENDED rather than rewritten. Its enforcement section still said report-only and its backlog still listed hardcodes that are now cleared, which left the record contradicting itself. The amendment says what changed and why the report-only period ended; the original text stays, because what the decision looked like when it was taken is the part worth keeping. Also corrects llms.txt's response envelope, which had errors at the top level and pagination at meta.total. Both are nested one deeper, so anything written against that description read undefined on every error it tried to handle.
This commit is contained in:
cproudlock
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-05-08
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-05-08
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-05-08
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-05-08
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
|
||||
## Context
|
||||
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-05-08
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-05-08
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-07-10
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-07-10
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** the "Migration strategy (resolved)" section of ADR-004
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-07-10
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-07-11
|
||||
- **Accepted:** 2026-07-11
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Supersedes:** none
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-07-11
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Relates to:** ADR-005 (equipment vs measuringtools scope), ADR-008 (plugin migration ownership)
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- **Status:** ACCEPTED
|
||||
- **Date:** 2026-07-13
|
||||
- **Deciders:** cproudlock
|
||||
- **Deciders:** ShopDB maintainers
|
||||
- **Relates to:** ADR-002 (plugin contract versioning), ADR-004 (per-site
|
||||
deployment), ADR-006 (collector contract), ADR-008 (per-plugin Alembic chains)
|
||||
|
||||
@@ -18,7 +18,7 @@ We want shopdb to own the manifests as data (author, version, publish, roll
|
||||
back) and to observe fleet compliance, while NOT taking on the GE-Enforce engine
|
||||
itself (which is the GE-Enforce framework's, maintained separately) and NOT
|
||||
dictating any site's imaging path (per ADR-004, each site is single-tenant with
|
||||
its own provisioning - PXE at West Jefferson, OOBE provisioning packages at
|
||||
its own provisioning - PXE at the reference site, OOBE provisioning packages at
|
||||
others).
|
||||
|
||||
The manifests are an enforcement PROGRAM, not an application inventory: entry
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- Status: PROPOSED
|
||||
- Date: 2026-07-18
|
||||
- Deciders: cproudlock
|
||||
- Deciders: ShopDB maintainers
|
||||
- Relates to: ADR-002 (contract versioning), ADR-003 (plugin distribution), ADR-004 (per-site instances), ADR-008 (per-plugin migrations), ADR-009 (frontend plugin gating), ADR-010 (frontend hook contract)
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- Status: ACCEPTED
|
||||
- Date: 2026-07-19
|
||||
- Deciders: cproudlock
|
||||
- Deciders: ShopDB maintainers
|
||||
- Relates to: ADR-008 (per-plugin migration ownership), ADR-013 (plugin catalog + lean per-site builds), ADR-001 (asset model)
|
||||
|
||||
## Context
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- Status: ACCEPTED
|
||||
- Date: 2026-08-11
|
||||
- Deciders: cproudlock
|
||||
- Deciders: ShopDB maintainers
|
||||
- Relates to: ADR-004 (per-site instances, not multi-tenant), ADR-013 (plugin catalog + lean per-site builds), ADR-014 (schema-lean per-site builds)
|
||||
|
||||
## Context
|
||||
@@ -23,11 +23,11 @@ shipped default or a hardcode rather than a comment:
|
||||
kiosk base URL now comes from the `site_base_url` setting at seed time and
|
||||
from HKLM at run time, and the dispatcher refuses rather than guessing when
|
||||
neither is set.
|
||||
- `plugins/backups/services/registry.py` defaults the backup share root to a WJ
|
||||
- `plugins/backups/services/registry.py` defaults the backup share root to one site's own
|
||||
UNC path.
|
||||
- `shopdb/core/api/settings.py` ships `device.geaerospace.net` and
|
||||
`Printer-{ip}.printer.geaerospace.net` as SETTING DEFAULTS, so another site
|
||||
inherits WJ's domain silently until someone notices.
|
||||
inherits that site's domain silently until someone notices.
|
||||
- `shopdb/core/models/dashboarddefault.py` holds the same domain a second time
|
||||
as a module constant, and `plugins/computers/api/routes.py` a third time as a
|
||||
literal fallback.
|
||||
@@ -55,7 +55,7 @@ site-specific default is the failure mode this ADR exists to stop: it is
|
||||
invisible, it looks deliberate, and it is wrong everywhere except here.
|
||||
|
||||
**2. A site-namespaced directory.** Anything that is genuinely one site's and
|
||||
will never be another's, such as the West Jefferson import loader at
|
||||
will never be another's, such as the reference site's import loader at
|
||||
`scripts/site_imports/wjf/`. Never reached by another site's build.
|
||||
|
||||
**3. Seed data, not code.** Vocabularies and catalogs, loaded by `flask seed`
|
||||
@@ -66,7 +66,7 @@ are a GE fleet taxonomy, not one site's data, and they already carry a per-site
|
||||
override through the `pctypemap_*` settings. They are out of scope here.
|
||||
|
||||
Comments and documentation may name a site where it explains WHY - "part markers
|
||||
share a machine number at West Jefferson" is a fact a maintainer needs. Prefer
|
||||
share a machine number at the reference site" is a fact a maintainer needs. Prefer
|
||||
phrasing the rule generally and the example specifically.
|
||||
|
||||
## Enforcement
|
||||
@@ -75,11 +75,9 @@ phrasing the rule generally and the example specifically.
|
||||
and `shopdb/` for a site host, a site FQDN or a site network, excluding tests
|
||||
and `site_imports/`.
|
||||
|
||||
It ships in REPORT-ONLY mode. It prints findings and does not fail the build,
|
||||
because turning a 19-item backlog into a hard gate on the day it lands blocks
|
||||
every unrelated commit until someone works through it. Set
|
||||
`SITE_LITERALS_ENFORCE=1` to make it a gate; do that once the real hardcodes
|
||||
below are cleared.
|
||||
It shipped in REPORT-ONLY mode, because turning a 19-item backlog into a hard
|
||||
gate on the day it lands blocks every unrelated commit until someone works
|
||||
through it. See the amendment below: it now fails the build.
|
||||
|
||||
## Consequences
|
||||
|
||||
@@ -101,7 +99,8 @@ Negative:
|
||||
|
||||
## Backlog
|
||||
|
||||
Real hardcodes and site-specific defaults, to clear before enforcing:
|
||||
CLEARED - see the amendment below. Kept as the record of what the decision was
|
||||
answering:
|
||||
|
||||
- `plugins/geenforce/seed_display_scope.py` - kiosk base URL, FQDN domain, and
|
||||
the legacy-shortcut sweep pattern
|
||||
@@ -116,5 +115,34 @@ setting, one default, one read.
|
||||
|
||||
Cosmetic mentions in comments and UI placeholder text are acceptable under this
|
||||
ADR and are not part of the backlog, with one exception worth fixing when
|
||||
convenient: the GE-Enforce settings page shows WJ's real CIDRs as its
|
||||
convenient: the GE-Enforce settings page shows one site's real CIDRs as its
|
||||
placeholder, which every site sees.
|
||||
|
||||
## Amendment, 2026-08-14
|
||||
|
||||
The backlog above is cleared and the scanner now ENFORCES: it fails the build,
|
||||
and `SITE_LITERALS_ENFORCE=0` is the escape hatch rather than the default. The
|
||||
report-only period ended for the reason the Consequences section predicted - the
|
||||
hit count did not move for weeks, because a rule that only prints is read as no
|
||||
rule.
|
||||
|
||||
Three things changed beyond clearing the list:
|
||||
|
||||
- The scan covers PowerShell, the installer, the seeds, generated JSON and the
|
||||
frontend, case-insensitively, across `plugins/`, `shopdb/`, `scripts/`,
|
||||
`deploy/`, `frontend/src/` and `tools/`. Its original scope - three file types
|
||||
under two directories - missed every literal that actually reached a second
|
||||
site, because those were all in the client scripts and the installer.
|
||||
- A line may declare itself deliberate with a trailing `ADR-015-OK: <reason>`
|
||||
marker. That is for an organisation-wide default which is right at every site
|
||||
and configurable anyway, such as the corporate device domain. It is not a
|
||||
way to defer work: the marker puts the claim in the diff where a reviewer
|
||||
sees it.
|
||||
- Both publication gates - the export scrub and the docs publishability test -
|
||||
carry the site patterns, which neither did. The ADR said this was not a
|
||||
security matter because the values were internal to an air-gapped network;
|
||||
that was true of the fleet and false of the public mirror, which had been
|
||||
carrying a production hostname and a share path.
|
||||
|
||||
This amendment is appended rather than edited into the text above, because what
|
||||
the decision looked like when it was taken is the part worth keeping.
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
- Status: ACCEPTED
|
||||
- Date: 2026-08-11
|
||||
- Deciders: cproudlock
|
||||
- Deciders: ShopDB maintainers
|
||||
- Relates to: ADR-006 (collector contract), ADR-012 (GE-Enforce manifest ownership), ADR-015 (site-specific configuration)
|
||||
|
||||
## Context
|
||||
|
||||
Reference in New Issue
Block a user