docs: add folder/repo rename design doc (scadalink-design → ScadaBridge)
This commit is contained in:
Joseph Doherty
@@ -0,0 +1,113 @@
|
||||
# Folder + Repo Rename `scadalink-design` → `ScadaBridge` — Design
|
||||
|
||||
**Date:** 2026-05-31
|
||||
**Status:** Approved, ready for implementation planning
|
||||
**Scope:** Rename the repo folder `~/Desktop/scadalink-design` → `~/Desktop/ScadaBridge`, rename the Gitea repository `dohertj2/scadalink-design` → `dohertj2/ScadaBridge`, and scrub every residual `scadalink`/`ScadaLink` reference inside the repo to its `ScadaBridge` equivalent.
|
||||
|
||||
This reverses the earlier decision (in `2026-05-28-scadabridge-rename-design.md`) to leave the folder name diverged from the product name, and completes the residual reference scrub that the earlier effort deliberately left out (the `SCADALINK_*` runtime env vars and the production deploy script).
|
||||
|
||||
## Context
|
||||
|
||||
The product was already renamed from "ScadaLink" to "ScadaBridge" in the `2026-05-28` effort: the solution (`ZB.MOM.WW.ScadaBridge.slnx`), all `src/`/`tests/` projects, namespaces, MS SQL databases, docker containers/network/image, the CLI config dir (`~/.scadabridge/`), `CLAUDE.md`, and `README.md` already say ScadaBridge. What remained untouched were the runtime environment variables (`SCADALINK_*`), one `.NET` config-key convention (`ScadaLink__*`), a stale assembly-name reference in the production deploy script, a few cosmetic identifiers, and historical doc/code-review mentions.
|
||||
|
||||
## Decisions
|
||||
|
||||
| # | Decision | Selected option |
|
||||
|---|----------|-----------------|
|
||||
| 1 | Folder-name collision (`~/Desktop/ScadaBridge` already exists — a separate, older, non-git project) | Rename the existing folder aside to `~/Desktop/ScadaBridge-old` (non-destructive); nothing deleted |
|
||||
| 2 | Reference scope | Full scrub — env vars, config keys, assembly name, SQL login, cosmetic identifiers, and historical docs/code-reviews |
|
||||
| 3 | Env-var cutover style | Hard cutover (no backward-compat fallback); dev stack is redeployed |
|
||||
| 4 | New env-var/identifier prefix | Short product name `SCADABRIDGE_` / `ScadaBridge__` (no `ZB.MOM.WW`), consistent with existing runtime artifacts (`scadabridge-*` containers, `~/.scadabridge/`) |
|
||||
| 5 | Gitea server-side rename | User renames via the Gitea web UI; Claude updates the local `origin` remote and verifies |
|
||||
| 6 | Execution mechanism | Scripted multi-pass `sed` over `git ls-files`, most-specific-first, with a completeness-gate `git grep` |
|
||||
| 7 | Migration records | Carved out of the scrub so their before→after meaning survives (see §2) |
|
||||
|
||||
## Section 1 — Order of operations
|
||||
|
||||
1. **Safety check** — confirm the working tree is clean (commit/stash WIP first); record the current branch.
|
||||
2. **Clear the collision** — `mv ~/Desktop/ScadaBridge ~/Desktop/ScadaBridge-old`.
|
||||
3. **Move the folder** — `mv ~/Desktop/scadalink-design ~/Desktop/ScadaBridge`. Plain OS move; git tracks contents, not the repo-root directory name, so history is untouched. `.idea/` and `.claude/` ride along inside the moved folder.
|
||||
4. **Scrub references** — run the scripted multi-pass `sed` (§2).
|
||||
5. **Build + test gate** — `dotnet build ZB.MOM.WW.ScadaBridge.slnx`, unit tests, completeness `git grep`.
|
||||
6. **Commit** (§5).
|
||||
7. **Runtime cutover** — rebuild + redeploy docker so running containers read the new env-var names (§4). No DB changes.
|
||||
8. **Gitea rename** — user web-UI rename; Claude updates local `origin` + verifies fetch/push.
|
||||
9. **Write/commit this design doc** (already produced by the brainstorm).
|
||||
|
||||
## Section 2 — The scrub
|
||||
|
||||
A new `tools/scrub-scadalink-refs.sh` operating on `git ls-files -z | xargs -0 sed -i ''` (skips `.git/` and `bin/obj` build artifacts), applied **most-specific-first** so a broad rule cannot double-replace an earlier result:
|
||||
|
||||
```
|
||||
1. ScadaLink.Host.exe → ZB.MOM.WW.ScadaBridge.Host.exe (stale assembly name, deploy/install.ps1)
|
||||
2. ScadaLink__ → ScadaBridge__ (.NET hierarchical config keys, deploy/install.ps1)
|
||||
3. SCADALINK_ → SCADABRIDGE_ (13 runtime env vars)
|
||||
4. scadaLinkVersion → scadaBridgeVersion (Transport param/local var — cosmetic)
|
||||
5. scadalink_app → scadabridge_app (SQL login)
|
||||
6. ScadaLink → ScadaBridge (residual)
|
||||
7. scadalink → scadabridge (residual)
|
||||
```
|
||||
|
||||
### The 13 `SCADALINK_*` env vars in scope
|
||||
|
||||
`SCADALINK_CONFIG`, `SCADALINK_FORMAT`, `SCADALINK_USERNAME`, `SCADALINK_PASSWORD`, `SCADALINK_MANAGEMENT_URL`, `SCADALINK_CONFIGURATIONDB_CONNECTION_STRING`, `SCADALINK_DESIGNTIME_CONNECTIONSTRING`, `SCADALINK_MSSQL_TEST_CONN`, `SCADALINK_PLAYWRIGHT_DB`, `SCADALINK_JWT_SIGNING_KEY`, `SCADALINK_LDAP_SERVICE_ACCOUNT_PASSWORD`, `SCADALINK_AUDIT_FILTER_4KB_P95_US`, `SCADALINK_AUDIT_FILTER_RAW_P95_US`.
|
||||
|
||||
They are read by code (`Environment.GetEnvironmentVariable(...)` in Host/CLI/tests) **and** set by `docker/docker-compose.yml`, `docker-env2/docker-compose.yml`, `appsettings.Central.json` (`${...}` placeholders), and `deploy/wonder-app-vd03/install.ps1`. All sites change together in one pass.
|
||||
|
||||
### Carved out (excluded — migration records)
|
||||
|
||||
Scrubbing these would destroy their before→after meaning:
|
||||
|
||||
- `tools/rename-to-scadabridge.sh` — prior rename tooling.
|
||||
- `docker/rename-databases.sh` — DB rename helper (`ALTER DATABASE ScadaLinkConfig MODIFY NAME = ScadaBridgeConfig`, `ALTER LOGIN [scadalink_app] ...`).
|
||||
- `docs/plans/2026-05-28-scadabridge-rename-design.md` — prior rename design.
|
||||
- `docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md` — **this document** (also a before→after record).
|
||||
|
||||
### Completeness gate
|
||||
|
||||
Must return only the four carve-outs:
|
||||
|
||||
```bash
|
||||
git grep -niE "scadalink" -- . \
|
||||
':!tools/rename-to-scadabridge.sh' \
|
||||
':!docker/rename-databases.sh' \
|
||||
':!docs/plans/2026-05-28-scadabridge-rename-design.md' \
|
||||
':!docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md'
|
||||
```
|
||||
|
||||
## Section 3 — Collision folder
|
||||
|
||||
The existing `~/Desktop/ScadaBridge` (non-git, older project containing `akka.md`, `netstd.md`, `CommentChecker`, its own `src/`/`tests/`/`tsdb/`) is renamed to `~/Desktop/ScadaBridge-old`. Nothing is deleted. If the user later confirms it is dead, they delete it themselves.
|
||||
|
||||
## Section 4 — Runtime cutover
|
||||
|
||||
Hard cutover. After the scrub, rebuild the image and `docker compose up -d --force-recreate` on both clusters (`docker/`, `docker-env2/`) so the running containers read `SCADABRIDGE_*`. **No database rename or wipe** — database names were already migrated in the `2026-05-28` effort and are unchanged here. If no stack is currently running, the cutover applies on the next `bash docker/deploy.sh`.
|
||||
|
||||
## Section 5 — Commits
|
||||
|
||||
Two staged commits on the current branch, `git diff`-reviewed between them:
|
||||
|
||||
1. `refactor: scrub residual ScadaLink refs → ScadaBridge (env vars, config keys, assembly name, SQL login)` — the scrub + any build/test fixes.
|
||||
2. `docs: add folder/repo rename design doc` — this document.
|
||||
|
||||
The folder `mv` and the Gitea rename are not git commits.
|
||||
|
||||
## Section 6 — Risks & rollback
|
||||
|
||||
- **Missed env var** → silent config-read failure. Mitigated by the completeness-gate grep + build/test + redeploy smoke check.
|
||||
- **Folder move breaks editor/Claude session paths** — the concern that drove the `2026-05-28` "don't rename the folder" decision; accepted by the user this time.
|
||||
- **Gitea redirect** — Gitea auto-redirects the old repo URL after rename, so pushes do not hard-fail even before the remote is updated; `origin` is updated regardless.
|
||||
- **Rollback** — pre-scrub state is the last git commit (`git reset --hard`); folder moves reverse with `mv`.
|
||||
|
||||
## Section 7 — Verification
|
||||
|
||||
- `dotnet build ZB.MOM.WW.ScadaBridge.slnx` clean; unit tests green.
|
||||
- Completeness grep returns only the four carve-outs.
|
||||
- `git remote -v` shows `https://gitea.dohertylan.com/dohertj2/ScadaBridge.git`; `git ls-remote origin` / `git fetch` succeeds.
|
||||
- (If a stack is running) CLI smoke against the redeployed cluster.
|
||||
|
||||
## Out of scope
|
||||
|
||||
- Renaming the MS SQL databases, docker containers/network, or CLI config dir — already done in the `2026-05-28` effort.
|
||||
- Sister repos `~/Desktop/MxAccessGateway`, `~/Desktop/OtOpcUa`.
|
||||
- Deleting `~/Desktop/ScadaBridge-old` — left to the user.
|
||||
Reference in New Issue
Block a user