docs: define the P1.1 registry layout and curator flow

2026-08-11 15:22:57 +02:00
parent a071e0baff
commit c2f33e58d7
5 changed files with 196 additions and 77 deletions
@@ -0,0 +1,38 @@
+# P1 to P1.1 registry layout migration
+
+P1.1 is a repository-contract cutover. New ThothII builds reject the old flat layout and a
+repository without `thoth-workspaces.yaml`, so migrate the registry in Git first and upgrade the
+application only after that reviewed migration commit is pushed.
+
+## One reviewed migration commit
+
+Perform the layout move in a clean review clone and keep it in one reviewed Git commit:
+
+```sh
+git mv workspaces/<id>.yaml <id>/workspace.yaml
+git mv workspace-content/<id>/evidence <id>/evidence
+# create and review thoth-workspaces.yaml from descriptor metadata
+```
+
+For every workspace directory, preserve the existing descriptor bytes, move only the embedded
+filesystem Evidence tree, and create `thoth-workspaces.yaml` with:
+
+- `schema_version: 1`
+- the ordered `workspaces` list
+- curator-owned `id`, `name`, and optional `description` copied from the reviewed descriptors
+
+Generated docs remain under `workspace-docs/<id>/`. Do not add an auto-migrator and do not let the
+API rewrite the catalog or Evidence tree.
+
+## Cutover order
+
+1. Review the migration commit, including the new `thoth-workspaces.yaml` metadata.
+2. Push that commit to the authoritative registry branch.
+3. Upgrade ThothII only after that migration commit is pushed.
+4. Pull the migrated registry into each installation before using workspace management.
+
+## Rollback
+
+Roll back the application revision and registry commit together. Do not point a P1.1 binary at the
+old flat layout, and do not keep a migrated registry commit active while rolling the application
+back to pre-P1.1 code.