Migrationsweg der Einstellungen von 9.x zurückbauen: config migrate, legacy_settings.py und die Ignore-Einträge der vier Altdateien .wikitool-*.json #211

New Issue

2026-10-11T09:09:45Z

torben commented

2026-10-11 09:09:45 +00:00

Angelegt am 2026-10-11 beim Abschluss von #208 (Stand 10.0.0-beta.2, 298b514), auf Wunsch des Betreibers. #208 Entwurf 3 hat die Ignore-Einträge bewusst stehen lassen und die Entfernung einem späteren Paket überlassen. Am selben Tag hat der Betreiber entschieden, dass sie erst mit dem ganzen Migrationsweg gehen (Entscheidung 1). Damit ist dieses Paket der Rückbau dieses Wegs.

Wartet auf einen Auslöser: die Entscheidung des Betreibers, ab wann ein Upgrade von 9.x nicht mehr unterstützt wird (Offene Frage 1). Vorher wird nichts gebaut.

Befund (gegen den Baum geprüft, 2026-10-11)

.gitignore Zeilen 118-126 halten vier Einträge für die Altdateien /.wikitool-remotes.json, /.wikitool-telemetry.json, /.wikitool-upload.json und /.wikitool-tasks.json. Der Kommentar dort begründet sie: Bis config migrate gelaufen ist, kann eine Altdatei noch ein Secret im Klartext tragen. Ohne den Eintrag nähme publish sie mit git add -A mit.
/.wikitool-tasks.d/ ist nicht Teil dieses Pakets. Die Profile existieren weiter (#208 Entscheidung 4), und der Eintrag bleibt.
Was eine verbliebene Altdatei anhält: publish endet nur bei .wikitool-remotes.json mit exit 42 (commands/git_publish.py, refuse_leftover("remotes")). task/review/new project halten bei .wikitool-tasks.json an, der MCP-Server bei .wikitool-upload.json, doctor meldet jede als FAIL. Eine verbliebene .wikitool-tasks.json mit Token im Klartext hält publish also nicht an; nur ihr Ignore-Eintrag hält den Token aus dem Commit.
.gitignore wird ausgeliefert (dist_cmd.py, Liste der Root-Dateien). Eine Änderung erreicht also jede Instanz mit ihrem Upgrade, auch einen Klon, der config migrate noch nicht ausgeführt hat (config migrate läuft pro Checkout, #208 Entwurf 1).
Bisher wurde kein Migrationsweg zurückgebaut. instructions/migrations/ hält alle Anleitungen seit 3.0.0. Einen Mechanismus, der ein Upgrade von einer zu alten Version verweigert, gibt es nicht (grep in tools/chemenu/ nach einer Mindestversion für das Upgrade ist leer).

Entscheidungen des Betreibers (2026-10-11)

Die Ignore-Einträge gehen erst mit dem Migrationsweg, nicht vorher. Bis ein Upgrade von 9.x nicht mehr unterstützt wird, ist eine verbliebene Altdatei ein erwarteter Zustand, und der Eintrag schützt genau ihn. Verworfen:
- publish bei jeder der vier Altdateien mit exit 42 anhalten und die Einträge sofort entfernen: schützt nicht gegen einen git add von Hand, und eine Altdatei erschiene in git status als unversionierte Datei;
- die Einträge dauerhaft behalten: dann bliebe Code für eine Form stehen, die keine unterstützte Version mehr schreibt.

Offene Fragen

Ab wann wird ein Upgrade von 9.x nicht mehr unterstützt? Das ist der Auslöser dieses Pakets (prio/waiting). Möglich wären etwa: die nächste MAJOR nach 10, ein Datum, oder wenn keine bekannte Instanz mehr auf 9.x steht. Das entscheidet der Betreiber.
Wie wird ein direktes Upgrade von < 10.0.0 auf die Version ohne Migrationsweg abgefangen? Ohne Sperre würde eine 9.x-Instanz die neue Maschinerie bekommen, ihre Altdateien nicht mehr gemeldet sehen und einen Token ungeschützt im Arbeitsbaum behalten. Dazu kommt, ob instructions/migrations/10.0.0-settings-tiers.md als Hinweis bleibt oder geht. Das ist eine Designfrage für stack-dev, sobald Frage 1 entschieden ist. Ein Vorschlag liegt noch nicht vor.

Invariante

Kein Secret-Wert aus einer Altdatei gelangt in den Git-Index, auch nicht in einem Checkout, der vor dem Rückbau nicht migriert hat. Das gilt in jeder Version, die eine Instanz erreichen kann. Entweder hält der Ignore-Eintrag die Altdatei aus dem Index, oder ein Upgrade dorthin ist nicht möglich, solange eine Altdatei im Checkout liegt.

Betroffene Dateien

.gitignore (Zeilen 118-126 samt Kommentar)
tools/chemenu/legacy_settings.py (entfällt), commands/config_cmd.py (config migrate samt Record), commands/doctor.py (check_legacy_settings), commands/_util.py (refuse_leftover), upload.py, tasks/config.py, mcp/__main__.py, commands/git_publish.py
je nach Frage 2: commands/dist_cmd.py und/oder version.py (Sperre für ein zu altes Upgrade), instructions/upgrade-instance.md
instructions/migrations/10.0.0-settings-tiers.md, instructions/migrate-corpus.md (Satz zu config migrate aus #208 Entwurf 1)
docs/reference/configuration.md (Abschnitt zu den Altdateien), docs/how-to/update-an-instance.md (Absatz zur Migration pro Checkout), docs/reference/commands/ und tools/CONTRACT.md (generiert), docs/explanation/version-model.md, falls die Mindestversion fürs Upgrade dort hingehört
Tests: test_config_cmd/Migrationstest, test_doctor.py, test_settings.py, test_tasks_config.py, die Tests der Sperre aus Frage 2

Akzeptanzkriterien

.gitignore enthält keinen der vier Einträge mehr; /.wikitool-tasks.d/ bleibt.
tools/wikitool config migrate existiert nicht mehr, und grep nach den vier Dateinamen in tools/chemenu/ außerhalb der Tests ist leer (bis auf eine Sperre aus Frage 2, falls sie die Namen braucht).
Ein Upgrade einer Instanz mit kb_version < 10.0.0, oder eines Checkouts mit einer der vier Altdateien, auf diese Version endet vor jeder Änderung am Baum mit exit 42 und nennt den Weg über eine 10.x-Version (Test).
In keinem Zustand, den dieses Paket zulässt, gelangt ein Token-Wert aus einer Altdatei durch ein wikitool-Kommando in den Git-Index (Test: Checkout mit .wikitool-tasks.json mit Token-Wert; Upgrade und publish --no-push enden ohne den Wert im Index, git grep findet ihn nicht).
docs verify, instructions verify, pytest grün; CI grün.

Versionsteil

--major. config migrate entfällt als Kommando, und ein Upgrade von 9.x ist nicht mehr direkt möglich (Katalog in instructions/dev/version-parts.md). Ob dafür eine eigene Migrationsanleitung nötig ist oder die Sperre aus Frage 2 genügt, wird im Design zusammen mit Frage 2 festgelegt.

> Angelegt am 2026-10-11 beim Abschluss von #208 (Stand `10.0.0-beta.2`, `298b514`), auf Wunsch des Betreibers. #208 Entwurf 3 hat die Ignore-Einträge bewusst stehen lassen und die Entfernung einem späteren Paket überlassen. Am selben Tag hat der Betreiber entschieden, dass sie erst mit dem ganzen Migrationsweg gehen (Entscheidung 1). Damit ist dieses Paket der Rückbau dieses Wegs. > > **Wartet auf einen Auslöser:** die Entscheidung des Betreibers, ab wann ein Upgrade von 9.x nicht mehr unterstützt wird (Offene Frage 1). Vorher wird nichts gebaut. ## Befund (gegen den Baum geprüft, 2026-10-11) - `.gitignore` Zeilen 118-126 halten vier Einträge für die Altdateien `/.wikitool-remotes.json`, `/.wikitool-telemetry.json`, `/.wikitool-upload.json` und `/.wikitool-tasks.json`. Der Kommentar dort begründet sie: Bis `config migrate` gelaufen ist, kann eine Altdatei noch ein Secret im Klartext tragen. Ohne den Eintrag nähme `publish` sie mit `git add -A` mit. - `/.wikitool-tasks.d/` ist **nicht** Teil dieses Pakets. Die Profile existieren weiter (#208 Entscheidung 4), und der Eintrag bleibt. - **Was eine verbliebene Altdatei anhält:** `publish` endet nur bei `.wikitool-remotes.json` mit exit 42 (`commands/git_publish.py`, `refuse_leftover("remotes")`). `task`/`review`/`new project` halten bei `.wikitool-tasks.json` an, der MCP-Server bei `.wikitool-upload.json`, `doctor` meldet jede als FAIL. Eine verbliebene `.wikitool-tasks.json` mit Token im Klartext hält `publish` also nicht an; nur ihr Ignore-Eintrag hält den Token aus dem Commit. - `.gitignore` wird ausgeliefert (`dist_cmd.py`, Liste der Root-Dateien). Eine Änderung erreicht also jede Instanz mit ihrem Upgrade, auch einen Klon, der `config migrate` noch nicht ausgeführt hat (`config migrate` läuft pro Checkout, #208 Entwurf 1). - **Bisher wurde kein Migrationsweg zurückgebaut.** `instructions/migrations/` hält alle Anleitungen seit 3.0.0. Einen Mechanismus, der ein Upgrade von einer zu alten Version verweigert, gibt es nicht (`grep` in `tools/chemenu/` nach einer Mindestversion für das Upgrade ist leer). ## Entscheidungen des Betreibers (2026-10-11) 1. **Die Ignore-Einträge gehen erst mit dem Migrationsweg, nicht vorher.** Bis ein Upgrade von 9.x nicht mehr unterstützt wird, ist eine verbliebene Altdatei ein erwarteter Zustand, und der Eintrag schützt genau ihn. Verworfen: - `publish` bei jeder der vier Altdateien mit exit 42 anhalten und die Einträge sofort entfernen: schützt nicht gegen einen `git add` von Hand, und eine Altdatei erschiene in `git status` als unversionierte Datei; - die Einträge dauerhaft behalten: dann bliebe Code für eine Form stehen, die keine unterstützte Version mehr schreibt. ## Offene Fragen 1. **Ab wann wird ein Upgrade von 9.x nicht mehr unterstützt?** Das ist der Auslöser dieses Pakets (`prio/waiting`). Möglich wären etwa: die nächste MAJOR nach 10, ein Datum, oder wenn keine bekannte Instanz mehr auf 9.x steht. Das entscheidet der Betreiber. 2. **Wie wird ein direktes Upgrade von < 10.0.0 auf die Version ohne Migrationsweg abgefangen?** Ohne Sperre würde eine 9.x-Instanz die neue Maschinerie bekommen, ihre Altdateien nicht mehr gemeldet sehen und einen Token ungeschützt im Arbeitsbaum behalten. Dazu kommt, ob `instructions/migrations/10.0.0-settings-tiers.md` als Hinweis bleibt oder geht. Das ist eine Designfrage für `stack-dev`, sobald Frage 1 entschieden ist. Ein Vorschlag liegt noch nicht vor. ## Invariante **Kein Secret-Wert aus einer Altdatei gelangt in den Git-Index**, auch nicht in einem Checkout, der vor dem Rückbau nicht migriert hat. Das gilt in jeder Version, die eine Instanz erreichen kann. Entweder hält der Ignore-Eintrag die Altdatei aus dem Index, oder ein Upgrade dorthin ist nicht möglich, solange eine Altdatei im Checkout liegt. ## Betroffene Dateien - `.gitignore` (Zeilen 118-126 samt Kommentar) - `tools/chemenu/legacy_settings.py` (entfällt), `commands/config_cmd.py` (`config migrate` samt Record), `commands/doctor.py` (`check_legacy_settings`), `commands/_util.py` (`refuse_leftover`), `upload.py`, `tasks/config.py`, `mcp/__main__.py`, `commands/git_publish.py` - je nach Frage 2: `commands/dist_cmd.py` und/oder `version.py` (Sperre für ein zu altes Upgrade), `instructions/upgrade-instance.md` - `instructions/migrations/10.0.0-settings-tiers.md`, `instructions/migrate-corpus.md` (Satz zu `config migrate` aus #208 Entwurf 1) - `docs/reference/configuration.md` (Abschnitt zu den Altdateien), `docs/how-to/update-an-instance.md` (Absatz zur Migration pro Checkout), `docs/reference/commands/` und `tools/CONTRACT.md` (generiert), `docs/explanation/version-model.md`, falls die Mindestversion fürs Upgrade dort hingehört - Tests: `test_config_cmd`/Migrationstest, `test_doctor.py`, `test_settings.py`, `test_tasks_config.py`, die Tests der Sperre aus Frage 2 ## Akzeptanzkriterien - [ ] `.gitignore` enthält keinen der vier Einträge mehr; `/.wikitool-tasks.d/` bleibt. - [ ] `tools/wikitool config migrate` existiert nicht mehr, und `grep` nach den vier Dateinamen in `tools/chemenu/` außerhalb der Tests ist leer (bis auf eine Sperre aus Frage 2, falls sie die Namen braucht). - [ ] Ein Upgrade einer Instanz mit `kb_version` < 10.0.0, oder eines Checkouts mit einer der vier Altdateien, auf diese Version endet vor jeder Änderung am Baum mit exit 42 und nennt den Weg über eine 10.x-Version (Test). - [ ] In keinem Zustand, den dieses Paket zulässt, gelangt ein Token-Wert aus einer Altdatei durch ein `wikitool`-Kommando in den Git-Index (Test: Checkout mit `.wikitool-tasks.json` mit Token-Wert; Upgrade und `publish --no-push` enden ohne den Wert im Index, `git grep` findet ihn nicht). - [ ] `docs verify`, `instructions verify`, `pytest` grün; CI grün. ## Versionsteil **`--major`.** `config migrate` entfällt als Kommando, und ein Upgrade von 9.x ist nicht mehr direkt möglich (Katalog in `instructions/dev/version-parts.md`). Ob dafür eine eigene Migrationsanleitung nötig ist oder die Sperre aus Frage 2 genügt, wird im Design zusammen mit Frage 2 festgelegt.

torben added the prio/waiting size/S area/distribution kind/decision labels 2026-10-11 09:09:45 +00:00

torben referenced this issue

2026-10-11 09:10:45 +00:00

Altlasten der Konfiguration bereinigen: die Einzeldateien `.wikitool-*.json` ziehen in die drei Stufen um und verschwinden #208

torben changed title from ~~Ignore-Einträge der vier Altdateien `.wikitool-*.json` entfernen, sobald keine unmigrierte Datei mehr ein Secret in `publish` tragen kann~~ to Migrationsweg der Einstellungen von 9.x zurückbauen: `config migrate`, `legacy_settings.py` und die Ignore-Einträge der vier Altdateien `.wikitool-*.json`

2026-10-11 09:12:12 +00:00

torben added size/M and removed size/S labels 2026-10-11 09:12:18 +00:00

torben commented

2026-10-11 09:12:18 +00:00

Changelog: Der Betreiber hat Option A gewählt (2026-10-11): Die Ignore-Einträge gehen erst mit dem Migrationsweg. B (Sperre in publish, Einträge sofort weg) und C (Einträge dauerhaft) stehen als verworfen in Entscheidung 1. Der Umfang wächst damit auf den Rückbau von config migrate und legacy_settings.py; Titel, betroffene Dateien und Kriterien sind entsprechend neu. Neu sind zwei offene Fragen: der Auslöser (ab wann kein Upgrade von 9.x mehr) und die Sperre gegen ein direktes Upgrade von < 10.0.0, für die es im Stack noch keinen Mechanismus gibt. Labels: size/S → size/M; kind/decision und prio/waiting bleiben bis zu Frage 1.

**Changelog:** Der Betreiber hat Option A gewählt (2026-10-11): Die Ignore-Einträge gehen erst mit dem Migrationsweg. B (Sperre in `publish`, Einträge sofort weg) und C (Einträge dauerhaft) stehen als verworfen in Entscheidung 1. Der Umfang wächst damit auf den Rückbau von `config migrate` und `legacy_settings.py`; Titel, betroffene Dateien und Kriterien sind entsprechend neu. Neu sind zwei offene Fragen: der Auslöser (ab wann kein Upgrade von 9.x mehr) und die Sperre gegen ein direktes Upgrade von < 10.0.0, für die es im Stack noch keinen Mechanismus gibt. Labels: `size/S` → `size/M`; `kind/decision` und `prio/waiting` bleiben bis zu Frage 1.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: torben/chemenu#211

Migrationsweg der Einstellungen von 9.x zurückbauen: config migrate, legacy_settings.py und die Ignore-Einträge der vier Altdateien .wikitool-*.json #211