From d941ed6ca51f69c290654e26be2beed14779d1e7 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Wed, 21 Oct 2026 20:55:13 +0100 Subject: [PATCH 1/6] Add the API-docs consumer wave plan Inventory and wave plan for adapting the SDK repositories to the `config` change that splits API-docs publishing from Maven publishing (`updateGitHubPages` -> `publishApiDocs`, no `publish` dependency). Phase 2 waits on the `config` merge and the close of the current wave. Co-Authored-By: Claude Opus 5.5 --- .agents/tasks/publish-api-docs-wave.md | 305 +++++++++++++++++++++++++ 1 file changed, 305 insertions(+) create mode 100644 .agents/tasks/publish-api-docs-wave.md diff --git a/.agents/tasks/publish-api-docs-wave.md b/.agents/tasks/publish-api-docs-wave.md new file mode 100644 index 0000000..e2d23a1 --- /dev/null +++ b/.agents/tasks/publish-api-docs-wave.md @@ -0,0 +1,305 @@ +--- +slug: publish-api-docs-wave +branch: publish-api-docs-wave +owner: claude +status: draft +started: 2026-10-21 +--- + +## Goal + +Every SDK repository in `summit` pulls the `config` that splits API-docs +publishing from Maven publishing, and none of its own Gradle files names +`updateGitHubPages` any more. `publish` no longer depends on the docs task, and +the docs reach GitHub Pages through the root `:publishApiDocs` task, run by the +new `publish-api-docs.yml` workflow on every push to `master`. + +This is a one-time job, and this file is the whole procedure. Do not turn it +into a skill. + +## Context + +- **The `config` change** is being made by the session "Publish API docs + separately from Maven" (worktree + `config/.claude/worktrees/publish-api-docs-a78bfa`, branch + `claude/publish-api-docs-a78bfa`). It builds on the `publishing-reliability` + hardening of `publishing.yml`. Its plan is in that worktree's + `.agents/tasks/publish-api-docs.md`. The user chose no deprecated aliases for + the old names. According to that plan: + - **Renames.** The package `io.spine.gradle.github.pages` stays. Classes become + `PublishApiDocs` and `PublishApiDocsExtension`, the DSL becomes + `fun Project.publishApiDocs { }` with the extension named `publishApiDocs`, + and the task name becomes `TaskName.publishApiDocs = "publishApiDocs"`. + `rootFolder` and `includeInputs` are unchanged, so each block body stays as + it is. + - **Root aggregate.** `spinePublishing { }` registers `:publishApiDocs`. It + depends on the `publishApiDocs` task of every published module that applies + the plugin, and does nothing in a repository without one. Consumers still + apply the plugin per module through the DSL, which is what Groups A–C below + rename. + - **Workflow.** `.github-workflows/publish-api-docs.yml` is self-contained, + with no reusable body and no `CONFIG_COMMIT` pin: every `./config/pull` + overwrites it, and a `config:replaces publish-api-docs.yml` directive holds + it back. It runs on push to `master`, decrypts the repository's own + `.github/keys/deploy_key_rsa.gpg` with that repository's + `GIT_CREDENTIALS_KEY` secret, and calls `./gradlew :publishApiDocs`. + `publishing.yml` loses the key decryption and the docs-only variables. + + The `config` session confirmed these names on 2026-10-21 and will report any + change made during review. +- **Consumers are safe until they pull.** Each repository's `publish.yml` pins + `publishing.yml@` and compiles its own `buildSrc`, so merging the + `config` PR breaks nothing by itself. The break comes with `./config/pull`: + after it, every consumer-owned reference to `updateGitHubPages` fails to + compile. The edit therefore lands in the same PR as the pull, as a separate + commit after it. +- **Stale files.** `config/migrate` copies `buildSrc` over the consumer's with + `cp -R` and never deletes anything, so plugin files that `config` renames would + survive in the consumer. `migrate` now deletes + `buildSrc/src/main/kotlin/io/spine/gradle/github/pages/UpdateGitHubPages.kt` + and `…/UpdateGitHubPagesExtension.kt` right after the copy. Its closing + `git add ./buildSrc/src` stages the deletions, so they land in the pull + commit. `TaskName.kt` stays; only its constant is renamed. The stale copies + could not compile anyway, because they refer to the removed constant. The wave + deletes nothing and only checks that nothing stale is left (step 2.1). + +## Inventory (2026-10-21) + +**Sources searched:** all 18 JVM repositories in `summit` (`git grep` on their +`cascade-refresh-604420c` branches, every tracked file except +`docs/dependencies/`), `BuildSpeed`, `documentation`, and the whole organization +via `gh search code`. The line numbers come from those branches, so re-grep +before editing. + +### Config-owned: the pull updates them, no hand edit + +In all 18 repositories these files are byte-identical to `config@604420c`: + +- `buildSrc/src/main/kotlin/io/spine/gradle/github/pages/*` is the plugin itself. + No repository has an extra file there, and no other `buildSrc` file outside + the list below references it. +- `buildSrc/src/main/kotlin/jvm-module.gradle.kts` contains + `publish?.dependsOn("${project.path}:updateGitHubPages")` (:156) and + `updateGitHubPages { }` (:165). +- `buildSrc/src/main/kotlin/DokkaExts.kt:279`: `docsShippingTaskNames`, the + Dokka gate. `publishApiDocs` must replace `updateGitHubPages` there, or the + docs task gets no Dokka output. +- `buildSrc/src/test/kotlin/io/spine/gradle/docs/DokkaSetupIgTest.kt`. + +### Consumer-owned: the wave edits these + +**Group A.** In these repositories, `setupPublishing()` or `setupDocPublishing()` +configures the docs and adds +`tasks.named("publish") { dependsOn("${project.path}:updateGitHubPages") }`. + +| Repository | File | Import | Function (call site) | +|---------------------|--------------------------------------------|--------|---------------------------------------| +| `core-jvm` | `buildSrc/src/main/kotlin/module.gradle.kts` | :54 | `Module.setupPublishing()` :257 (:93) | +| `jdbc-storage` | `buildSrc/src/main/kotlin/module.gradle.kts` | :53 | `Module.setupPublishing()` :229 (:92) | +| `delivery` | `buildSrc/src/main/kotlin/module.gradle.kts` | :50 | `Module.setupPublishing()` :386 (:116) | +| `gcloud-jvm` | `build.gradle.kts` (root) | :47 | `Project.setupPublishing()` :612 (:191) | +| `compiler` | `buildSrc/src/main/kotlin/module.gradle.kts` | :36 | `Module.setupDocPublishing()` :152 (:75) | +| `validation` | `buildSrc/src/main/kotlin/module.gradle.kts` | :50 | `Module.setupDocPublishing()` :239 (:91) | +| `core-jvm-compiler` | `buildSrc/src/main/kotlin/module.gradle.kts` | :55 | `Module.setupDocPublishing()` :300 (:103) | +| `ProtoTap` | `buildSrc/src/main/kotlin/module.gradle.kts` | :56 | `Module.setupDocPublishing()` :298 (:103) | + +Edit (`core-jvm` shown): + +```diff +-import io.spine.gradle.github.pages.updateGitHubPages ++import io.spine.gradle.github.pages.publishApiDocs + ... +- setupPublishing() ++ setupDocPublishing() + ... + /** +- * Configures publishing for this subproject. ++ * Configures documentation publishing for this subproject. + */ +-fun Module.setupPublishing() { +- updateGitHubPages { ++fun Module.setupDocPublishing() { ++ publishApiDocs { + rootFolder.set(rootDir) + } +- +- tasks.named("publish") { +- dependsOn("${project.path}:updateGitHubPages") +- } + } +``` + +Delete the `publish` dependency; do not rename it to `publishApiDocs`, which +would couple the two jobs again. Left in place, it fails `publish` when Gradle +builds the task graph ("Task with path ':x:updateGitHubPages' not found"). The +same applies to the Group B hook. + +The rename from `setupPublishing` to `setupDocPublishing`, with its KDoc and +call site, applies only to the four repositories that use the first name. Once +the `publish` wiring is gone the function configures documentation only, and +the other four already call it that. + +**Group B.** In these repositories, `configureGitHubPages()` configures the docs, +and an `afterEvaluate` hook inside `setTaskDependencies()` wires `publish` to +the docs task. + +| Repository | File | Import | `afterEvaluate` hook | `configureGitHubPages()` | +|------------------|--------------------------------------------|--------|----------------------|--------------------------| +| `base-libraries` | `buildSrc/src/main/kotlin/module.gradle.kts` | :28 | :172–175 | :182 | +| `testlib` | `buildSrc/src/main/kotlin/module.gradle.kts` | :28 | :144–147 | :154 | +| `time` | `buildSrc/src/main/kotlin/module.gradle.kts` | :45 | :182–185 | :192 | + +Edit: + +```diff +-import io.spine.gradle.github.pages.updateGitHubPages ++import io.spine.gradle.github.pages.publishApiDocs + ... + clean.configure { + dependsOn(cleanGenerated) + } +- +- project.afterEvaluate { +- val publish = tasks.findByName("publish") +- publish?.dependsOn("${project.path}:updateGitHubPages") +- } + } + ... + fun Module.configureGitHubPages() { +- updateGitHubPages { ++ publishApiDocs { + rootFolder.set(rootDir) + } + } +``` + +`time` writes the call as `updateGitHubPages() {`. In `testlib`, +`configureGitHubPages()` also declares an unused `val docletVersion`. Leave it: +it is not part of this change. + +**Group C.** These repositories call the DSL but never wired it to `publish`. + +| Repository | File | Import | Call | +|-------------|--------------------------------------------|--------|----------------------------------------------| +| `tool-base` | `buildSrc/src/main/kotlin/module.gradle.kts` | :41 | inside `configureGitHubPages()` :159 | +| `change` | `buildSrc/src/main/kotlin/module.gradle.kts` | :42 | top level, `updateGitHubPages() {` :114 | + +Edit: rename the import and the call. Nothing else changes. + +**Behaviour change.** Because `publish` never ran the docs task here, the +newest commit on the `gh-pages` branch of each of these two repositories is +`Add CNAME for gh-pages`, dated 2025-12-02 in `tool-base` and 2025-12-22 in +`change`; no documentation update has landed since. Once `publish-api-docs.yml` runs `publishApiDocs` on +`master`, they start publishing API docs: the root aggregate picks up every +published module that applies the plugin. The user approved this on 2026-10-21, +so the edit stays rename-only. + +**Group D: pull only.** `reflect`, `logging`, `dokka-tools`, `base-types`, and +`money` get the docs wiring from the config-owned `jvm-module` script and own +no reference to it. + +**Not affected:** `BuildSpeed` is verify-only and has no references. +`documentation` is not a JVM consumer. + +### Outside `summit`: not in this wave + +- **`Chords`** (pins `config@838f9a02`, last pushed 2026-10-21) and + **`Chords-Gradle-plugin`** (`config@dcd2cee3`) carry the old + `io.spine.internal.gradle.github.pages` copy. `Chords/.github/workflows/publish.yml:56` + runs `publish -x updateGitHubPages`. Their next `./config/pull` is a migration + in its own right, and this edit becomes part of it. The `-x` must go, because + Gradle fails on an excluded task it cannot find. + **Behaviour change:** after that pull, the new workflow publishes their docs. + If that is not wanted, drop their plugin call; decide when they pull. +- **`elastic`** (`config@c2aae6e7`, last pushed 2026-07-06) references the task + only in `jvm-module.gradle.kts`, which `config` owns (checked file by file on + `master`), so it needs nothing beyond its next pull. +- **`doc-tools`**, **`gradle-execfork-plugin`**, and **`users`** have been dormant + since 2021–2023. **`web`**, **`dart`**, **`text`**, **`model-compiler`**, and + **`model-tools`** are archived. Ignore all of them. + +## Wave plan + +**Mechanism:** a regular `refresh` cascade wave +([`docs/rollout/rebuild.md`](../../docs/rollout/rebuild.md)) against the `config` +commit that carries the change, plus one hand-edit commit per repository. A +refresh wave fits for three reasons: + +- The edit can land neither before the pull (the new DSL does not exist yet) + nor after it (the pull alone breaks the build). +- Every PR needs a version bump anyway. +- `cascade` already handles dependency order, pins, and the publish gates. + +The edit adds no ordering constraint of its own, because every change is +confined to the repository's own build logic. + +### Gates + +- [ ] G1. The `config` PRs are merged: publishing reliability and the API-docs + split. Record the merge sha; it names the wave. +- [x] G2. The `config` session confirmed the names and the `migrate` deletions + on 2026-10-21. Re-check only if it reports a name change from review. +- [ ] G3. Wave `cascade-refresh-604420c` is closed (`cascade plan` refuses to + run over open `cascade-*` PRs). +- [ ] G4. The user says go. + +### Steps + +- [ ] 1. Run `./cascade plan --kind refresh`, producing + `cascade-refresh-`. Review the order: 18 libraries in canonical + order, with `BuildSpeed` parked as usual. +- [ ] 2. For each repository, in wave order, run the cascade loop with one + insertion: `PREP:` (pull commit, pins, bump) → **hand edit** → + `BUILD:` → `PREPR:` → `SHIP:`. The hand edit has three + parts: + 1. **Stale-file check.** After the pull, run + `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'`. Only the + consumer-owned files listed for the repository's group should match. A + hit in a config-owned path is a retired file that `migrate` missed. + Remove it with `git rm` if it is byte-identical to a blob `config` once + shipped at that path (check with `git -C config log --raw -- buildSrc`), + and commit as "Remove stale `buildSrc` files". + 2. **Group edit.** Apply the edit for the repository's group (A, B, or C), + and commit it as "Publish API docs separately from `publish`". Group D + repositories skip this part. + 3. **Proof.** Use dry runs only: a real `publishApiDocs` run pushes to + `gh-pages`. Run the checks between wave builds, never alongside one. + - `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'` finds nothing. + - `./gradlew publish -m` lists none of `publishApiDocs`, + `updateGitHubPages`, `copyJavadocDocs`, or `copyHtmlDocs`. + - `./gradlew :publishApiDocs -m`, the command the workflow runs, plans + the `publishApiDocs` task of each published module that is + documented. In `tool-base` and `change` this list is new. +- [ ] 3. Commit and PR rules: `cascade` makes its own PREP and BUILD commits. The + hand-edit commits and `SHIP` (push plus draft PR) happen only at the + user's explicit request (AGENTS.md). Post each PR link as it is opened. +- [ ] 4. After each merge, watch two runs: the repository's first `Publish` run, + which must no longer touch the docs, and its first `publish-api-docs.yml` + run, which must put the docs on `gh-pages`. A failed docs run does not + block downstream repositories, because the registry is unaffected. It is + not a `FIX-PUBLISH`; fix it afterwards. +- [ ] 5. Run `CLOSE` as usual. Then delete this file together with the wave's + state pair. + +## Log + +- 2026-10-21. Drafted from the inventory above. Waiting on the `config` merge, + the `config` session's answers, and the user's go. +- 2026-10-21. The user decided that `tool-base` and `change` start publishing + API docs: Group C keeps the rename-only edit. +- 2026-10-21. The `config` plan (`publish-api-docs.md`) answered the open + questions: `migrate` deletes the stale files, the DSL is + `Project.publishApiDocs { }`, and the workflow is a self-contained distributed + file that runs `:publishApiDocs`. Updated the context, step 2.1, and the + proof. +- 2026-10-21. The `config` session confirmed the names, the retired paths, and + the workflow's secret (`GIT_CREDENTIALS_KEY`); G2 is done. Its hand-over lists + `change` with a `publish` dependency, and `web`, `dart`, `elastic`, `text`, + `model-compiler`, and `model-tools` as affected, based on local clones. + Checked against GitHub: `change` has only the DSL call (Group C), `elastic` + references only the config-owned `jvm-module`, and the other five are + archived. +- 2026-10-21. Moved to branch `publish-api-docs-wave`, cut from + `origin/master` in a separate worktree, to keep the plan off the in-flight + wave's branch. The wave itself (Phase 2) still runs from the main `summit` + checkout, which has the repositories on disk. From 590deec631eb38fdff6205845d155205b0193cb7 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 22 Oct 2026 18:04:35 +0100 Subject: [PATCH 2/6] Track config#815 updates in the API-docs wave plan Snapshot versions skip only the `gh-pages` push, the root aggregate is named `publishAllApiDocs`, and `migrate` retires a third file, `Update.kt`. Since snapshots never clone or push `gh-pages`, add a step to watch the first release version's docs run. Co-Authored-By: Claude Opus 5.5 --- .agents/tasks/publish-api-docs-wave.md | 102 ++++++++++++++++++------- 1 file changed, 74 insertions(+), 28 deletions(-) diff --git a/.agents/tasks/publish-api-docs-wave.md b/.agents/tasks/publish-api-docs-wave.md index e2d23a1..f10a99b 100644 --- a/.agents/tasks/publish-api-docs-wave.md +++ b/.agents/tasks/publish-api-docs-wave.md @@ -11,7 +11,7 @@ started: 2026-10-21 Every SDK repository in `summit` pulls the `config` that splits API-docs publishing from Maven publishing, and none of its own Gradle files names `updateGitHubPages` any more. `publish` no longer depends on the docs task, and -the docs reach GitHub Pages through the root `:publishApiDocs` task, run by the +the docs reach GitHub Pages through the root `publishAllApiDocs` task, run by the new `publish-api-docs.yml` workflow on every push to `master`. This is a one-time job, and this file is the whole procedure. Do not turn it @@ -32,9 +32,11 @@ into a skill. and the task name becomes `TaskName.publishApiDocs = "publishApiDocs"`. `rootFolder` and `includeInputs` are unchanged, so each block body stays as it is. - - **Root aggregate.** `spinePublishing { }` registers `:publishApiDocs`. It - depends on the `publishApiDocs` task of every published module that applies - the plugin, and does nothing in a repository without one. Consumers still + - **Root aggregate.** `spinePublishing { }` registers `publishAllApiDocs`, a + name only the root project has. It depends on the `publishApiDocs` task of + every published module that applies the plugin, and does nothing in a + repository without one. In a single-project repository it runs the root's + own `publishApiDocs`. Consumers still apply the plugin per module through the DSL, which is what Groups A–C below rename. - **Workflow.** `.github-workflows/publish-api-docs.yml` is self-contained, @@ -42,11 +44,22 @@ into a skill. overwrites it, and a `config:replaces publish-api-docs.yml` directive holds it back. It runs on push to `master`, decrypts the repository's own `.github/keys/deploy_key_rsa.gpg` with that repository's - `GIT_CREDENTIALS_KEY` secret, and calls `./gradlew :publishApiDocs`. + `GIT_CREDENTIALS_KEY` secret, and calls `./gradlew :publishAllApiDocs`. `publishing.yml` loses the key decryption and the docs-only variables. The `config` session confirmed these names on 2026-10-21 and will report any change made during review. +- **Snapshot versions push no docs to `gh-pages`.** config#815 restored this at + the user's request on 2026-10-22. On a `-SNAPSHOT.N` version, each module's + `publishApiDocs` only logs that it skips the docs, so the docs run + (`publishAllApiDocs`, and the workflow) ends green without generating or + pushing anything. Maven publishing is unaffected: Dokka still builds the + Javadoc and HTML archives of every version, snapshots included, and `publish` + still uploads them to the Maven repositories. Every SDK + repository is on a snapshot version, and the wave bumps within that line. So + after the wave, `gh-pages` stops changing until each repository's next + release version, whereas until now every merge pushed the snapshot's docs. + Commits on `gh-pages` are now authored by `PublishApiDocs Plugin`. - **Consumers are safe until they pull.** Each repository's `publish.yml` pins `publishing.yml@` and compiles its own `buildSrc`, so merging the `config` PR breaks nothing by itself. The break comes with `./config/pull`: @@ -55,13 +68,14 @@ into a skill. commit after it. - **Stale files.** `config/migrate` copies `buildSrc` over the consumer's with `cp -R` and never deletes anything, so plugin files that `config` renames would - survive in the consumer. `migrate` now deletes - `buildSrc/src/main/kotlin/io/spine/gradle/github/pages/UpdateGitHubPages.kt` - and `…/UpdateGitHubPagesExtension.kt` right after the copy. Its closing - `git add ./buildSrc/src` stages the deletions, so they land in the pull - commit. `TaskName.kt` stays; only its constant is renamed. The stale copies - could not compile anyway, because they refer to the removed constant. The wave - deletes nothing and only checks that nothing stale is left (step 2.1). + survive in the consumer. Right after the copy, `migrate` now deletes three + retired files from `buildSrc/src/main/kotlin/io/spine/gradle/github/pages/`: + `UpdateGitHubPages.kt`, `UpdateGitHubPagesExtension.kt`, and `Update.kt` (now + `DocsPublication.kt`). Its closing `git add ./buildSrc/src` stages the + deletions, so they land in the pull commit. `TaskName.kt` stays; only its + constant is renamed. The stale copies could not compile anyway, because they + refer to the removed names. The wave deletes nothing and only checks that + nothing stale is left (step 2.1). ## Inventory (2026-10-21) @@ -189,10 +203,11 @@ Edit: rename the import and the call. Nothing else changes. **Behaviour change.** Because `publish` never ran the docs task here, the newest commit on the `gh-pages` branch of each of these two repositories is `Add CNAME for gh-pages`, dated 2025-12-02 in `tool-base` and 2025-12-22 in -`change`; no documentation update has landed since. Once `publish-api-docs.yml` runs `publishApiDocs` on -`master`, they start publishing API docs: the root aggregate picks up every -published module that applies the plugin. The user approved this on 2026-10-21, -so the edit stays rename-only. +`change`; no documentation update has landed since. Once +`publish-api-docs.yml` runs `publishApiDocs` on `master`, they start +publishing API docs from their next release version: the root aggregate picks +up every published module that applies the plugin. The user approved this on +2026-10-21, so the edit stays rename-only. **Group D: pull only.** `reflect`, `logging`, `dokka-tools`, `base-types`, and `money` get the docs wiring from the config-owned `jvm-module` script and own @@ -209,8 +224,10 @@ no reference to it. runs `publish -x updateGitHubPages`. Their next `./config/pull` is a migration in its own right, and this edit becomes part of it. The `-x` must go, because Gradle fails on an excluded task it cannot find. - **Behaviour change:** after that pull, the new workflow publishes their docs. - If that is not wanted, drop their plugin call; decide when they pull. + **Behaviour change:** after that pull, the new workflow publishes their docs + from their next release version. Check then that each repository has + `.github/keys/deploy_key_rsa.gpg` and the `GIT_CREDENTIALS_KEY` secret. If + publishing is not wanted, drop their plugin call; decide when they pull. - **`elastic`** (`config@c2aae6e7`, last pushed 2026-07-06) references the task only in `jvm-module.gradle.kts`, which `config` owns (checked file by file on `master`), so it needs nothing beyond its next pull. @@ -235,8 +252,10 @@ confined to the repository's own build logic. ### Gates -- [ ] G1. The `config` PRs are merged: publishing reliability and the API-docs - split. Record the merge sha; it names the wave. +- [ ] G1. The `config` PRs are merged. config#814 ("Make the `Publish` + workflow reliable") merged on 2026-10-22 as `ad3dff0890`. config#815 + ("Publish API docs apart from Maven publishing") is open against + `master`. Record its merge sha; it names the wave. - [x] G2. The `config` session confirmed the names and the `migrate` deletions on 2026-10-21. Re-check only if it reports a name change from review. - [ ] G3. Wave `cascade-refresh-604420c` is closed (`cascade plan` refuses to @@ -262,24 +281,38 @@ confined to the repository's own build logic. 2. **Group edit.** Apply the edit for the repository's group (A, B, or C), and commit it as "Publish API docs separately from `publish`". Group D repositories skip this part. - 3. **Proof.** Use dry runs only: a real `publishApiDocs` run pushes to - `gh-pages`. Run the checks between wave builds, never alongside one. + 3. **Proof.** Use dry runs only: on a release version, a real + `publishApiDocs` run pushes to `gh-pages`. Run the checks between wave + builds, never alongside one. - `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'` finds nothing. - `./gradlew publish -m` lists none of `publishApiDocs`, `updateGitHubPages`, `copyJavadocDocs`, or `copyHtmlDocs`. - - `./gradlew :publishApiDocs -m`, the command the workflow runs, plans + - `./gradlew publishAllApiDocs -m`, the task the workflow runs, plans the `publishApiDocs` task of each published module that is - documented. In `tool-base` and `change` this list is new. + documented. In `tool-base` and `change` this list is new. On a + snapshot version it lists no `copyJavadocDocs` or `copyHtmlDocs`, + because snapshots push no docs to `gh-pages`. - [ ] 3. Commit and PR rules: `cascade` makes its own PREP and BUILD commits. The hand-edit commits and `SHIP` (push plus draft PR) happen only at the user's explicit request (AGENTS.md). Post each PR link as it is opened. - [ ] 4. After each merge, watch two runs: the repository's first `Publish` run, which must no longer touch the docs, and its first `publish-api-docs.yml` - run, which must put the docs on `gh-pages`. A failed docs run does not - block downstream repositories, because the registry is unaffected. It is - not a `FIX-PUBLISH`; fix it afterwards. + run, which must end green. On a snapshot version, `PublishApiDocs` + registers a do-nothing task in place of the real one. That run decrypts + the deploy key in a workflow step, then logs for each documented module + that the docs are not published. It registers no SSH key, clones + nothing, and pushes nothing, so it proves only the decryption and the + task graph. A failed docs run does not block downstream repositories, + because the registry is unaffected. It is not a `FIX-PUBLISH`; fix it + afterwards. +- [ ] 4a. After the wave, on the first release version of any repository: watch + its `publish-api-docs.yml` run. It is the first real use of the sparse + `gh-pages` clone and push from config#815. Its commits read "Publish the + `` documentation of the module …". Report a failure at the clone + or push step to the `config` session, or on config#815 if it has merged. - [ ] 5. Run `CLOSE` as usual. Then delete this file together with the wave's - state pair. + state pair. If step 4a is still open at that point, move it into the + task note of the next release first. ## Log @@ -303,3 +336,16 @@ confined to the repository's own build logic. `origin/master` in a separate worktree, to keep the plan off the in-flight wave's branch. The wave itself (Phase 2) still runs from the main `summit` checkout, which has the repositories on disk. +- 2026-10-22. config#814 merged; config#815 now targets `master` and skips the + API docs of snapshot versions. Names and consumer edits are unchanged. Updated + the context, Group C, the Chords note, G1, the proof, and step 4: a green first + docs run on a snapshot proves the wiring only. +- 2026-10-22. config#815 renamed the root aggregate to `publishAllApiDocs`, + and the workflow now runs `./gradlew :publishAllApiDocs`. The module DSL and + task stay `publishApiDocs`, so the consumer edits are unchanged; only the + proof command changed. +- 2026-10-22. config#815 (`10643809`) retires a third file, `Update.kt` (now + `DocsPublication.kt`), which `migrate` also deletes, and clones `gh-pages` + sparsely. Snapshots get a do-nothing task, so the wave never runs the clone or + push; added step 4a for the first release version, and told the `config` + session. From b812455ff8d1f327f905c3a707746d58ed405086 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 22 Oct 2026 18:52:49 +0100 Subject: [PATCH 3/6] Apply the documentation review to the API-docs wave plan Fix the nested lists in step 2, the stale task name in Group C, and a step-name reference that `master` does not define. Drop the repeated `File` column from the inventory tables, and reflow lines. Co-Authored-By: Claude Opus 5.5 --- .agents/tasks/publish-api-docs-wave.md | 150 +++++++++++++------------ 1 file changed, 78 insertions(+), 72 deletions(-) diff --git a/.agents/tasks/publish-api-docs-wave.md b/.agents/tasks/publish-api-docs-wave.md index f10a99b..08130ef 100644 --- a/.agents/tasks/publish-api-docs-wave.md +++ b/.agents/tasks/publish-api-docs-wave.md @@ -30,15 +30,14 @@ into a skill. `PublishApiDocs` and `PublishApiDocsExtension`, the DSL becomes `fun Project.publishApiDocs { }` with the extension named `publishApiDocs`, and the task name becomes `TaskName.publishApiDocs = "publishApiDocs"`. - `rootFolder` and `includeInputs` are unchanged, so each block body stays as - it is. + `rootFolder` and `includeInputs` are unchanged, so the body of each block + stays as it is. - **Root aggregate.** `spinePublishing { }` registers `publishAllApiDocs`, a name only the root project has. It depends on the `publishApiDocs` task of every published module that applies the plugin, and does nothing in a repository without one. In a single-project repository it runs the root's - own `publishApiDocs`. Consumers still - apply the plugin per module through the DSL, which is what Groups A–C below - rename. + own `publishApiDocs`. Consumers still apply the plugin per module through + the DSL, which is what Groups A–C below rename. - **Workflow.** `.github-workflows/publish-api-docs.yml` is self-contained, with no reusable body and no `CONFIG_COMMIT` pin: every `./config/pull` overwrites it, and a `config:replaces publish-api-docs.yml` directive holds @@ -49,13 +48,13 @@ into a skill. The `config` session confirmed these names on 2026-10-21 and will report any change made during review. -- **Snapshot versions push no docs to `gh-pages`.** config#815 restored this at - the user's request on 2026-10-22. On a `-SNAPSHOT.N` version, each module's - `publishApiDocs` only logs that it skips the docs, so the docs run - (`publishAllApiDocs`, and the workflow) ends green without generating or - pushing anything. Maven publishing is unaffected: Dokka still builds the - Javadoc and HTML archives of every version, snapshots included, and `publish` - still uploads them to the Maven repositories. Every SDK +- **Snapshot versions push no docs to `gh-pages`.** The change in config#815 + restored this at the user's request on 2026-10-22. On a `-SNAPSHOT.N` + version, each module's `publishApiDocs` only logs that it skips the docs, so + the docs run (`publishAllApiDocs`, and the workflow) ends green without + generating or pushing anything. Maven publishing is unaffected: Dokka still + builds the Javadoc and HTML archives of every version, snapshots included, + and `publish` still uploads them to the Maven repositories. Every SDK repository is on a snapshot version, and the wave bumps within that line. So after the wave, `gh-pages` stops changing until each repository's next release version, whereas until now every merge pushed the snapshot's docs. @@ -77,13 +76,13 @@ into a skill. refer to the removed names. The wave deletes nothing and only checks that nothing stale is left (step 2.1). -## Inventory (2026-10-21) +## Inventory (2026-10-21, updated 2026-10-22) **Sources searched:** all 18 JVM repositories in `summit` (`git grep` on their `cascade-refresh-604420c` branches, every tracked file except `docs/dependencies/`), `BuildSpeed`, `documentation`, and the whole organization via `gh search code`. The line numbers come from those branches, so re-grep -before editing. +them before editing. ### Config-owned: the pull updates them, no hand edit @@ -105,17 +104,19 @@ In all 18 repositories these files are byte-identical to `config@604420c`: **Group A.** In these repositories, `setupPublishing()` or `setupDocPublishing()` configures the docs and adds `tasks.named("publish") { dependsOn("${project.path}:updateGitHubPages") }`. - -| Repository | File | Import | Function (call site) | -|---------------------|--------------------------------------------|--------|---------------------------------------| -| `core-jvm` | `buildSrc/src/main/kotlin/module.gradle.kts` | :54 | `Module.setupPublishing()` :257 (:93) | -| `jdbc-storage` | `buildSrc/src/main/kotlin/module.gradle.kts` | :53 | `Module.setupPublishing()` :229 (:92) | -| `delivery` | `buildSrc/src/main/kotlin/module.gradle.kts` | :50 | `Module.setupPublishing()` :386 (:116) | -| `gcloud-jvm` | `build.gradle.kts` (root) | :47 | `Project.setupPublishing()` :612 (:191) | -| `compiler` | `buildSrc/src/main/kotlin/module.gradle.kts` | :36 | `Module.setupDocPublishing()` :152 (:75) | -| `validation` | `buildSrc/src/main/kotlin/module.gradle.kts` | :50 | `Module.setupDocPublishing()` :239 (:91) | -| `core-jvm-compiler` | `buildSrc/src/main/kotlin/module.gradle.kts` | :55 | `Module.setupDocPublishing()` :300 (:103) | -| `ProtoTap` | `buildSrc/src/main/kotlin/module.gradle.kts` | :56 | `Module.setupDocPublishing()` :298 (:103) | +The code is in `buildSrc/src/main/kotlin/module.gradle.kts`, except in +`gcloud-jvm`, which keeps it in its root `build.gradle.kts`. + +| Repository | Import | Function (call site) | +|---------------------|--------|-------------------------------------------| +| `core-jvm` | :54 | `Module.setupPublishing()` :257 (:93) | +| `jdbc-storage` | :53 | `Module.setupPublishing()` :229 (:92) | +| `delivery` | :50 | `Module.setupPublishing()` :386 (:116) | +| `gcloud-jvm` | :47 | `Project.setupPublishing()` :612 (:191) | +| `compiler` | :36 | `Module.setupDocPublishing()` :152 (:75) | +| `validation` | :50 | `Module.setupDocPublishing()` :239 (:91) | +| `core-jvm-compiler` | :55 | `Module.setupDocPublishing()` :300 (:103) | +| `ProtoTap` | :56 | `Module.setupDocPublishing()` :298 (:103) | Edit (`core-jvm` shown): @@ -150,18 +151,18 @@ same applies to the Group B hook. The rename from `setupPublishing` to `setupDocPublishing`, with its KDoc and call site, applies only to the four repositories that use the first name. Once -the `publish` wiring is gone the function configures documentation only, and +the `publish` wiring is gone, the function configures documentation only, and the other four already call it that. **Group B.** In these repositories, `configureGitHubPages()` configures the docs, and an `afterEvaluate` hook inside `setTaskDependencies()` wires `publish` to -the docs task. +the docs task. The code is in `buildSrc/src/main/kotlin/module.gradle.kts`. -| Repository | File | Import | `afterEvaluate` hook | `configureGitHubPages()` | -|------------------|--------------------------------------------|--------|----------------------|--------------------------| -| `base-libraries` | `buildSrc/src/main/kotlin/module.gradle.kts` | :28 | :172–175 | :182 | -| `testlib` | `buildSrc/src/main/kotlin/module.gradle.kts` | :28 | :144–147 | :154 | -| `time` | `buildSrc/src/main/kotlin/module.gradle.kts` | :45 | :182–185 | :192 | +| Repository | Import | `afterEvaluate` hook | `configureGitHubPages()` | +|------------------|--------|----------------------|--------------------------| +| `base-libraries` | :28 | :172–175 | :182 | +| `testlib` | :28 | :144–147 | :154 | +| `time` | :45 | :182–185 | :192 | Edit: @@ -191,12 +192,13 @@ Edit: `configureGitHubPages()` also declares an unused `val docletVersion`. Leave it: it is not part of this change. -**Group C.** These repositories call the DSL but never wired it to `publish`. +**Group C.** These repositories call the DSL but have never wired it to +`publish`. The code is in `buildSrc/src/main/kotlin/module.gradle.kts`. -| Repository | File | Import | Call | -|-------------|--------------------------------------------|--------|----------------------------------------------| -| `tool-base` | `buildSrc/src/main/kotlin/module.gradle.kts` | :41 | inside `configureGitHubPages()` :159 | -| `change` | `buildSrc/src/main/kotlin/module.gradle.kts` | :42 | top level, `updateGitHubPages() {` :114 | +| Repository | Import | Call | +|-------------|--------|-----------------------------------------| +| `tool-base` | :41 | inside `configureGitHubPages()` :159 | +| `change` | :42 | top level, `updateGitHubPages() {` :114 | Edit: rename the import and the call. Nothing else changes. @@ -204,16 +206,16 @@ Edit: rename the import and the call. Nothing else changes. newest commit on the `gh-pages` branch of each of these two repositories is `Add CNAME for gh-pages`, dated 2025-12-02 in `tool-base` and 2025-12-22 in `change`; no documentation update has landed since. Once -`publish-api-docs.yml` runs `publishApiDocs` on `master`, they start +`publish-api-docs.yml` runs `publishAllApiDocs` on `master`, they start publishing API docs from their next release version: the root aggregate picks up every published module that applies the plugin. The user approved this on 2026-10-21, so the edit stays rename-only. -**Group D: pull only.** `reflect`, `logging`, `dokka-tools`, `base-types`, and -`money` get the docs wiring from the config-owned `jvm-module` script and own -no reference to it. +**Group D.** `reflect`, `logging`, `dokka-tools`, `base-types`, and `money` need +only the pull. They get the docs wiring from the config-owned `jvm-module` +script and own no reference to it. -**Not affected:** `BuildSpeed` is verify-only and has no references. +**Not affected.** `BuildSpeed` is verify-only and has no references. `documentation` is not a JVM consumer. ### Outside `summit`: not in this wave @@ -224,7 +226,7 @@ no reference to it. runs `publish -x updateGitHubPages`. Their next `./config/pull` is a migration in its own right, and this edit becomes part of it. The `-x` must go, because Gradle fails on an excluded task it cannot find. - **Behaviour change:** after that pull, the new workflow publishes their docs + **Behaviour change.** After that pull, the new workflow publishes their docs from their next release version. Check then that each repository has `.github/keys/deploy_key_rsa.gpg` and the `GIT_CREDENTIALS_KEY` secret. If publishing is not wanted, drop their plugin call; decide when they pull. @@ -240,10 +242,10 @@ no reference to it. **Mechanism:** a regular `refresh` cascade wave ([`docs/rollout/rebuild.md`](../../docs/rollout/rebuild.md)) against the `config` commit that carries the change, plus one hand-edit commit per repository. A -refresh wave fits for three reasons: +refresh wave fits here for three reasons: -- The edit can land neither before the pull (the new DSL does not exist yet) - nor after it (the pull alone breaks the build). +- The edit can land neither in an earlier PR than the pull (the new DSL does + not exist yet) nor in a later one (the pull alone breaks the build). - Every PR needs a version bump anyway. - `cascade` already handles dependency order, pins, and the publish gates. @@ -252,12 +254,13 @@ confined to the repository's own build logic. ### Gates -- [ ] G1. The `config` PRs are merged. config#814 ("Make the `Publish` - workflow reliable") merged on 2026-10-22 as `ad3dff0890`. config#815 - ("Publish API docs apart from Maven publishing") is open against - `master`. Record its merge sha; it names the wave. +- [ ] G1. The `config` PRs are merged. The first, config#814 ("Make the + `Publish` workflow reliable"), merged on 2026-10-22 as `ad3dff0890`. The + second, config#815 ("Publish API docs apart from Maven publishing"), is + open against `master`. Record its merge sha; it names the wave. - [x] G2. The `config` session confirmed the names and the `migrate` deletions - on 2026-10-21. Re-check only if it reports a name change from review. + on 2026-10-21, and added the third retired file, `Update.kt`, on + 2026-10-22. Re-check only if it reports a name change from review. - [ ] G3. Wave `cascade-refresh-604420c` is closed (`cascade plan` refuses to run over open `cascade-*` PRs). - [ ] G4. The user says go. @@ -269,42 +272,41 @@ confined to the repository's own build logic. order, with `BuildSpeed` parked as usual. - [ ] 2. For each repository, in wave order, run the cascade loop with one insertion: `PREP:` (pull commit, pins, bump) → **hand edit** → - `BUILD:` → `PREPR:` → `SHIP:`. The hand edit has three - parts: - 1. **Stale-file check.** After the pull, run + `BUILD:` → `PREPR:` → `SHIP:`. The hand edit has three parts: + 1. **Stale-file check.** After the pull, run `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'`. Only the consumer-owned files listed for the repository's group should match. A hit in a config-owned path is a retired file that `migrate` missed. Remove it with `git rm` if it is byte-identical to a blob `config` once shipped at that path (check with `git -C config log --raw -- buildSrc`), and commit as "Remove stale `buildSrc` files". - 2. **Group edit.** Apply the edit for the repository's group (A, B, or C), + 2. **Group edit.** Apply the edit for the repository's group (A, B, or C), and commit it as "Publish API docs separately from `publish`". Group D repositories skip this part. - 3. **Proof.** Use dry runs only: on a release version, a real + 3. **Proof.** Use dry runs only: on a release version, a real `publishApiDocs` run pushes to `gh-pages`. Run the checks between wave builds, never alongside one. - `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'` finds nothing. - `./gradlew publish -m` lists none of `publishApiDocs`, `updateGitHubPages`, `copyJavadocDocs`, or `copyHtmlDocs`. - - `./gradlew publishAllApiDocs -m`, the task the workflow runs, plans + - `./gradlew :publishAllApiDocs -m`, the task the workflow runs, plans the `publishApiDocs` task of each published module that is documented. In `tool-base` and `change` this list is new. On a snapshot version it lists no `copyJavadocDocs` or `copyHtmlDocs`, because snapshots push no docs to `gh-pages`. -- [ ] 3. Commit and PR rules: `cascade` makes its own PREP and BUILD commits. The - hand-edit commits and `SHIP` (push plus draft PR) happen only at the - user's explicit request (AGENTS.md). Post each PR link as it is opened. +- [ ] 3. Commit and PR rules: `cascade` makes its own `PREP` and `BUILD` commits. + The hand-edit commits and `SHIP` (push plus draft PR) happen only at the + user's explicit request (`AGENTS.md`). Post each PR link as it is opened. - [ ] 4. After each merge, watch two runs: the repository's first `Publish` run, which must no longer touch the docs, and its first `publish-api-docs.yml` run, which must end green. On a snapshot version, `PublishApiDocs` - registers a do-nothing task in place of the real one. That run decrypts - the deploy key in a workflow step, then logs for each documented module - that the docs are not published. It registers no SSH key, clones + registers a do-nothing task in place of the real one. That docs run + decrypts the deploy key in a workflow step, then logs for each documented + module that the docs are not published. It registers no SSH key, clones nothing, and pushes nothing, so it proves only the decryption and the task graph. A failed docs run does not block downstream repositories, - because the registry is unaffected. It is not a `FIX-PUBLISH`; fix it - afterwards. + because the registry is unaffected, so fix it afterwards instead of + treating it as a failed publish. - [ ] 4a. After the wave, on the first release version of any repository: watch its `publish-api-docs.yml` run. It is the first real use of the sparse `gh-pages` clone and push from config#815. Its commits read "Publish the @@ -312,7 +314,7 @@ confined to the repository's own build logic. or push step to the `config` session, or on config#815 if it has merged. - [ ] 5. Run `CLOSE` as usual. Then delete this file together with the wave's state pair. If step 4a is still open at that point, move it into the - task note of the next release first. + task file of the next release first. ## Log @@ -323,15 +325,15 @@ confined to the repository's own build logic. - 2026-10-21. The `config` plan (`publish-api-docs.md`) answered the open questions: `migrate` deletes the stale files, the DSL is `Project.publishApiDocs { }`, and the workflow is a self-contained distributed - file that runs `:publishApiDocs`. Updated the context, step 2.1, and the - proof. + file that runs `:publishApiDocs`. Updated the context, step 2.1, and + the proof. - 2026-10-21. The `config` session confirmed the names, the retired paths, and the workflow's secret (`GIT_CREDENTIALS_KEY`); G2 is done. Its hand-over lists `change` with a `publish` dependency, and `web`, `dart`, `elastic`, `text`, `model-compiler`, and `model-tools` as affected, based on local clones. Checked against GitHub: `change` has only the DSL call (Group C), `elastic` - references only the config-owned `jvm-module`, and the other five are - archived. + references only the config-owned `jvm-module`, and the other five + are archived. - 2026-10-21. Moved to branch `publish-api-docs-wave`, cut from `origin/master` in a separate worktree, to keep the plan off the in-flight wave's branch. The wave itself (Phase 2) still runs from the main `summit` @@ -347,5 +349,9 @@ confined to the repository's own build logic. - 2026-10-22. config#815 (`10643809`) retires a third file, `Update.kt` (now `DocsPublication.kt`), which `migrate` also deletes, and clones `gh-pages` sparsely. Snapshots get a do-nothing task, so the wave never runs the clone or - push; added step 4a for the first release version, and told the `config` - session. + push; added step 4a for the first release version, and told + the `config` session. +- 2026-10-22. Applied the pre-PR documentation review: fixed the nested lists + in step 2, the stale task name in Group C, and the reference to + `FIX-PUBLISH`, which `master` does not define yet; dropped the repeated + `File` column from the tables. From 137c3debb4928c3a30e39ae0e39a4dc750ecfd75 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 22 Oct 2026 19:02:04 +0100 Subject: [PATCH 4/6] Map the `delivery` and `delivery-server` names in the wave plan `summit`'s `master` still names the submodule `delivery-server`, while the GitHub repository is now `delivery`, the name the in-flight wave branch adopts. Say that both names mean the same repository. Co-Authored-By: Claude Opus 5.5 --- .agents/tasks/publish-api-docs-wave.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/.agents/tasks/publish-api-docs-wave.md b/.agents/tasks/publish-api-docs-wave.md index 08130ef..36b8c47 100644 --- a/.agents/tasks/publish-api-docs-wave.md +++ b/.agents/tasks/publish-api-docs-wave.md @@ -84,6 +84,12 @@ into a skill. via `gh search code`. The line numbers come from those branches, so re-grep them before editing. +**Repository names.** `delivery` is the GitHub repository +`SpineEventEngine/delivery`, formerly `delivery-server`; the old name redirects. +`summit`'s `master` still names the submodule `delivery-server`, and summit#5 +renames it to `delivery` (`1fdd7cf`). Where a checkout still says +`delivery-server`, it is the same repository and takes the same edit. + ### Config-owned: the pull updates them, no hand edit In all 18 repositories these files are byte-identical to `config@604420c`: @@ -355,3 +361,6 @@ confined to the repository's own build logic. in step 2, the stale task name in Group C, and the reference to `FIX-PUBLISH`, which `master` does not define yet; dropped the repeated `File` column from the tables. +- 2026-10-22. A review asked to rename `delivery` to `delivery-server`, the name + on `summit`'s `master`. Kept `delivery`, the current GitHub name, which + summit#5 adopts, and added a note that maps the two names. From 05d205049251fcf884fafbe7123b20f956830bcd Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Wed, 4 Nov 2026 19:36:05 +0000 Subject: [PATCH 5/6] Revise the API-docs wave plan for config#817 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit config#817 makes `./config/pull` rewrite the consumer scripts, so the hand edits the plan listed are no longer needed. Eleven repositories already took the change; the plan now tracks the seven that remain, replaces the hand-edit steps with checks of the pull's output, and tightens the context. G1–G3 are done; only the user's go remains. Co-Authored-By: Claude Opus 5.5 --- .agents/tasks/publish-api-docs-wave.md | 394 ++++++++----------------- 1 file changed, 120 insertions(+), 274 deletions(-) diff --git a/.agents/tasks/publish-api-docs-wave.md b/.agents/tasks/publish-api-docs-wave.md index 36b8c47..b683d00 100644 --- a/.agents/tasks/publish-api-docs-wave.md +++ b/.agents/tasks/publish-api-docs-wave.md @@ -19,305 +19,145 @@ into a skill. ## Context -- **The `config` change** is being made by the session "Publish API docs - separately from Maven" (worktree - `config/.claude/worktrees/publish-api-docs-a78bfa`, branch - `claude/publish-api-docs-a78bfa`). It builds on the `publishing-reliability` - hardening of `publishing.yml`. Its plan is in that worktree's - `.agents/tasks/publish-api-docs.md`. The user chose no deprecated aliases for - the old names. According to that plan: - - **Renames.** The package `io.spine.gradle.github.pages` stays. Classes become - `PublishApiDocs` and `PublishApiDocsExtension`, the DSL becomes - `fun Project.publishApiDocs { }` with the extension named `publishApiDocs`, - and the task name becomes `TaskName.publishApiDocs = "publishApiDocs"`. - `rootFolder` and `includeInputs` are unchanged, so the body of each block - stays as it is. - - **Root aggregate.** `spinePublishing { }` registers `publishAllApiDocs`, a - name only the root project has. It depends on the `publishApiDocs` task of - every published module that applies the plugin, and does nothing in a - repository without one. In a single-project repository it runs the root's - own `publishApiDocs`. Consumers still apply the plugin per module through - the DSL, which is what Groups A–C below rename. - - **Workflow.** `.github-workflows/publish-api-docs.yml` is self-contained, - with no reusable body and no `CONFIG_COMMIT` pin: every `./config/pull` - overwrites it, and a `config:replaces publish-api-docs.yml` directive holds - it back. It runs on push to `master`, decrypts the repository's own - `.github/keys/deploy_key_rsa.gpg` with that repository's - `GIT_CREDENTIALS_KEY` secret, and calls `./gradlew :publishAllApiDocs`. - `publishing.yml` loses the key decryption and the docs-only variables. - - The `config` session confirmed these names on 2026-10-21 and will report any - change made during review. -- **Snapshot versions push no docs to `gh-pages`.** The change in config#815 - restored this at the user's request on 2026-10-22. On a `-SNAPSHOT.N` - version, each module's `publishApiDocs` only logs that it skips the docs, so - the docs run (`publishAllApiDocs`, and the workflow) ends green without - generating or pushing anything. Maven publishing is unaffected: Dokka still - builds the Javadoc and HTML archives of every version, snapshots included, - and `publish` still uploads them to the Maven repositories. Every SDK - repository is on a snapshot version, and the wave bumps within that line. So - after the wave, `gh-pages` stops changing until each repository's next - release version, whereas until now every merge pushed the snapshot's docs. - Commits on `gh-pages` are now authored by `PublishApiDocs Plugin`. -- **Consumers are safe until they pull.** Each repository's `publish.yml` pins - `publishing.yml@` and compiles its own `buildSrc`, so merging the - `config` PR breaks nothing by itself. The break comes with `./config/pull`: - after it, every consumer-owned reference to `updateGitHubPages` fails to - compile. The edit therefore lands in the same PR as the pull, as a separate - commit after it. -- **Stale files.** `config/migrate` copies `buildSrc` over the consumer's with - `cp -R` and never deletes anything, so plugin files that `config` renames would - survive in the consumer. Right after the copy, `migrate` now deletes three - retired files from `buildSrc/src/main/kotlin/io/spine/gradle/github/pages/`: - `UpdateGitHubPages.kt`, `UpdateGitHubPagesExtension.kt`, and `Update.kt` (now - `DocsPublication.kt`). Its closing `git add ./buildSrc/src` stages the - deletions, so they land in the pull commit. `TaskName.kt` stays; only its - constant is renamed. The stale copies could not compile anyway, because they - refer to the removed names. The wave deletes nothing and only checks that - nothing stale is left (step 2.1). - -## Inventory (2026-10-21, updated 2026-10-22) - -**Sources searched:** all 18 JVM repositories in `summit` (`git grep` on their -`cascade-refresh-604420c` branches, every tracked file except -`docs/dependencies/`), `BuildSpeed`, `documentation`, and the whole organization -via `gh search code`. The line numbers come from those branches, so re-grep -them before editing. - -**Repository names.** `delivery` is the GitHub repository -`SpineEventEngine/delivery`, formerly `delivery-server`; the old name redirects. -`summit`'s `master` still names the submodule `delivery-server`, and summit#5 -renames it to `delivery` (`1fdd7cf`). Where a checkout still says -`delivery-server`, it is the same repository and takes the same edit. - -### Config-owned: the pull updates them, no hand edit - -In all 18 repositories these files are byte-identical to `config@604420c`: - -- `buildSrc/src/main/kotlin/io/spine/gradle/github/pages/*` is the plugin itself. - No repository has an extra file there, and no other `buildSrc` file outside - the list below references it. -- `buildSrc/src/main/kotlin/jvm-module.gradle.kts` contains - `publish?.dependsOn("${project.path}:updateGitHubPages")` (:156) and - `updateGitHubPages { }` (:165). -- `buildSrc/src/main/kotlin/DokkaExts.kt:279`: `docsShippingTaskNames`, the - Dokka gate. `publishApiDocs` must replace `updateGitHubPages` there, or the - docs task gets no Dokka output. -- `buildSrc/src/test/kotlin/io/spine/gradle/docs/DokkaSetupIgTest.kt`. - -### Consumer-owned: the wave edits these - -**Group A.** In these repositories, `setupPublishing()` or `setupDocPublishing()` -configures the docs and adds -`tasks.named("publish") { dependsOn("${project.path}:updateGitHubPages") }`. -The code is in `buildSrc/src/main/kotlin/module.gradle.kts`, except in -`gcloud-jvm`, which keeps it in its root `build.gradle.kts`. - -| Repository | Import | Function (call site) | -|---------------------|--------|-------------------------------------------| -| `core-jvm` | :54 | `Module.setupPublishing()` :257 (:93) | -| `jdbc-storage` | :53 | `Module.setupPublishing()` :229 (:92) | -| `delivery` | :50 | `Module.setupPublishing()` :386 (:116) | -| `gcloud-jvm` | :47 | `Project.setupPublishing()` :612 (:191) | -| `compiler` | :36 | `Module.setupDocPublishing()` :152 (:75) | -| `validation` | :50 | `Module.setupDocPublishing()` :239 (:91) | -| `core-jvm-compiler` | :55 | `Module.setupDocPublishing()` :300 (:103) | -| `ProtoTap` | :56 | `Module.setupDocPublishing()` :298 (:103) | - -Edit (`core-jvm` shown): - -```diff --import io.spine.gradle.github.pages.updateGitHubPages -+import io.spine.gradle.github.pages.publishApiDocs - ... -- setupPublishing() -+ setupDocPublishing() - ... - /** -- * Configures publishing for this subproject. -+ * Configures documentation publishing for this subproject. - */ --fun Module.setupPublishing() { -- updateGitHubPages { -+fun Module.setupDocPublishing() { -+ publishApiDocs { - rootFolder.set(rootDir) - } -- -- tasks.named("publish") { -- dependsOn("${project.path}:updateGitHubPages") -- } - } -``` - -Delete the `publish` dependency; do not rename it to `publishApiDocs`, which -would couple the two jobs again. Left in place, it fails `publish` when Gradle -builds the task graph ("Task with path ':x:updateGitHubPages' not found"). The -same applies to the Group B hook. - -The rename from `setupPublishing` to `setupDocPublishing`, with its KDoc and -call site, applies only to the four repositories that use the first name. Once -the `publish` wiring is gone, the function configures documentation only, and -the other four already call it that. - -**Group B.** In these repositories, `configureGitHubPages()` configures the docs, -and an `afterEvaluate` hook inside `setTaskDependencies()` wires `publish` to -the docs task. The code is in `buildSrc/src/main/kotlin/module.gradle.kts`. - -| Repository | Import | `afterEvaluate` hook | `configureGitHubPages()` | -|------------------|--------|----------------------|--------------------------| -| `base-libraries` | :28 | :172–175 | :182 | -| `testlib` | :28 | :144–147 | :154 | -| `time` | :45 | :182–185 | :192 | - -Edit: - -```diff --import io.spine.gradle.github.pages.updateGitHubPages -+import io.spine.gradle.github.pages.publishApiDocs - ... - clean.configure { - dependsOn(cleanGenerated) - } -- -- project.afterEvaluate { -- val publish = tasks.findByName("publish") -- publish?.dependsOn("${project.path}:updateGitHubPages") -- } - } - ... - fun Module.configureGitHubPages() { -- updateGitHubPages { -+ publishApiDocs { - rootFolder.set(rootDir) - } - } -``` - -`time` writes the call as `updateGitHubPages() {`. In `testlib`, -`configureGitHubPages()` also declares an unused `val docletVersion`. Leave it: -it is not part of this change. - -**Group C.** These repositories call the DSL but have never wired it to -`publish`. The code is in `buildSrc/src/main/kotlin/module.gradle.kts`. - -| Repository | Import | Call | -|-------------|--------|-----------------------------------------| -| `tool-base` | :41 | inside `configureGitHubPages()` :159 | -| `change` | :42 | top level, `updateGitHubPages() {` :114 | - -Edit: rename the import and the call. Nothing else changes. - -**Behaviour change.** Because `publish` never ran the docs task here, the -newest commit on the `gh-pages` branch of each of these two repositories is -`Add CNAME for gh-pages`, dated 2025-12-02 in `tool-base` and 2025-12-22 in -`change`; no documentation update has landed since. Once -`publish-api-docs.yml` runs `publishAllApiDocs` on `master`, they start -publishing API docs from their next release version: the root aggregate picks -up every published module that applies the plugin. The user approved this on -2026-10-21, so the edit stays rename-only. - -**Group D.** `reflect`, `logging`, `dokka-tools`, `base-types`, and `money` need -only the pull. They get the docs wiring from the config-owned `jvm-module` -script and own no reference to it. - -**Not affected.** `BuildSpeed` is verify-only and has no references. -`documentation` is not a JVM consumer. +- **The `config` change.** SpineEventEngine/config#815 (merged 2026-10-22 as + `58cd2d4a31`) splits API-docs publishing from Maven publishing; its plan is + `config/.agents/tasks/publish-api-docs.md`. The package + `io.spine.gradle.github.pages` stays, and there are no deprecated aliases. + - **Renames.** `UpdateGitHubPages` becomes `PublishApiDocs`, + `UpdateGitHubPagesExtension` becomes `PublishApiDocsExtension`, the DSL and + extension `updateGitHubPages` become `publishApiDocs`, and + `TaskName.updateGitHubPages` becomes `TaskName.publishApiDocs`. Block bodies + stay as they are: `rootFolder` and `includeInputs` are unchanged. + - **Root aggregate.** `spinePublishing { }` registers `publishAllApiDocs`. It + depends on the `publishApiDocs` task of every published module that applies + the plugin, and does nothing where there is none. + - **Workflow.** The distributed `publish-api-docs.yml` runs + `./gradlew :publishAllApiDocs` on every push to `master`, after decrypting + the repository's own `deploy_key_rsa.gpg` with its `GIT_CREDENTIALS_KEY` + secret. `publishing.yml` no longer touches the docs. +- **The pull rewrites consumer scripts.** `migrate` deletes the three retired + plugin files (`UpdateGitHubPages.kt`, `UpdateGitHubPagesExtension.kt`, and + `Update.kt`). Since SpineEventEngine/config#817 (merged 2026-10-22), it also + runs `scripts/migrate-publish-api-docs.sh`. That script renames the import and + the call, deletes the `publish` dependency in both known forms + (`tasks.named("publish") { … }` and an `afterEvaluate` hook), renames + `configureGitHubPages()` to `configureApiDocs()`, and reports any use it + cannot rewrite. `cascade prep` commits the rewrite with the pull. +- **Consumers are safe until they pull.** Each `publish.yml` pins + `publishing.yml@` and compiles the repository's own `buildSrc`, so + the `config` merge breaks nothing by itself; the pull brings the new API and + the rewrite together. +- **Snapshot versions push no docs to `gh-pages`.** On a `-SNAPSHOT.N` version, + each module's `publishApiDocs` only logs a skip, so the docs run ends green + without generating or pushing anything. Dokka and `publish` still build and + upload the Javadoc and HTML archives. The wave keeps every repository on + snapshots, so `gh-pages` stops changing until each one's next release; until + now, every merge pushed its snapshot's docs. + +## Status (2026-11-04) + +Checked on each repository's `master`. + +**Done: 11 repositories.** `tool-base`, `ProtoTap`, `compiler`, `validation`, +`core-jvm-compiler`, `time`, `money`, `core-jvm`, `jdbc-storage`, `gcloud-jvm`, +and `delivery` already pull a `config` with the split. Most got it in the +`cascade-refresh-604420c` wave, whose `./config/pull` took the latest `config` +`master` after 2026-10-22; the others in their own PRs. Each has +`PublishApiDocs.kt` and `publish-api-docs.yml`, no reference to the old names, +and no `publish` dependency on the docs. Every `publish-api-docs.yml` run so far +is green; all of them ran on snapshot versions, so they skipped the docs. + +**Remaining: 7 repositories,** still on a `config` from before config#815. + +| Repository | `config` pin | What the pull changes in the repository's own files | +|------------------|--------------|---------------------------------------------------------| +| `base-libraries` | `604420cd` | `module.gradle.kts`: import, call, `afterEvaluate` hook | +| `testlib` | `604420cd` | `module.gradle.kts`: import, call, `afterEvaluate` hook | +| `change` | `ad3dff08` | `module.gradle.kts`: import and top-level call | +| `reflect` | `604420cd` | nothing; only config-owned files name the old API | +| `logging` | `a53eca4b` | nothing | +| `dokka-tools` | `604420cd` | nothing | +| `base-types` | `ad3dff08` | nothing | + +In `base-libraries` and `testlib` the script also renames +`configureGitHubPages()` to `configureApiDocs()`. A dry run of +`config/scripts/migrate-publish-api-docs.sh` on copies of these files from +`master` (2026-11-04) rewrote `base-libraries`, `testlib`, and `change` +completely and reported nothing, so no hand edit is expected. + +**Behaviour change.** `change` has never wired the docs to `publish`, so its +`gh-pages` has had no documentation since 2025-12-22. After the pull, it +publishes API docs from its next release version, as approved on 2026-10-21. +`tool-base`, the other such repository, is already done. ### Outside `summit`: not in this wave -- **`Chords`** (pins `config@838f9a02`, last pushed 2026-10-21) and - **`Chords-Gradle-plugin`** (`config@dcd2cee3`) carry the old - `io.spine.internal.gradle.github.pages` copy. `Chords/.github/workflows/publish.yml:56` - runs `publish -x updateGitHubPages`. Their next `./config/pull` is a migration - in its own right, and this edit becomes part of it. The `-x` must go, because - Gradle fails on an excluded task it cannot find. - **Behaviour change.** After that pull, the new workflow publishes their docs - from their next release version. Check then that each repository has - `.github/keys/deploy_key_rsa.gpg` and the `GIT_CREDENTIALS_KEY` secret. If - publishing is not wanted, drop their plugin call; decide when they pull. -- **`elastic`** (`config@c2aae6e7`, last pushed 2026-07-06) references the task - only in `jvm-module.gradle.kts`, which `config` owns (checked file by file on - `master`), so it needs nothing beyond its next pull. +- **`Chords`** (pins `config@838f9a02`) and **`Chords-Gradle-plugin`** + (`config@dcd2cee3`) carry the old `io.spine.internal.gradle.github.pages` + copy, and `Chords`' `publish.yml` runs `publish -x updateGitHubPages`. Their + next `./config/pull` is a migration in its own right. It overwrites that + `publish.yml`, and the rewrite script reports any other workflow that names + the old task. **Behaviour change.** The new workflow then publishes their + docs from their next release version. Check that each repository has + `.github/keys/deploy_key_rsa.gpg` and the `GIT_CREDENTIALS_KEY` secret, or + drop their plugin call if publishing is not wanted. +- **`elastic`** (`config@c2aae6e7`) names the old API only in config-owned + files, so its next pull is enough. - **`doc-tools`**, **`gradle-execfork-plugin`**, and **`users`** have been dormant since 2021–2023. **`web`**, **`dart`**, **`text`**, **`model-compiler`**, and **`model-tools`** are archived. Ignore all of them. ## Wave plan -**Mechanism:** a regular `refresh` cascade wave -([`docs/rollout/rebuild.md`](../../docs/rollout/rebuild.md)) against the `config` -commit that carries the change, plus one hand-edit commit per repository. A -refresh wave fits here for three reasons: - -- The edit can land neither in an earlier PR than the pull (the new DSL does - not exist yet) nor in a later one (the pull alone breaks the build). -- Every PR needs a version bump anyway. -- `cascade` already handles dependency order, pins, and the publish gates. - -The edit adds no ordering constraint of its own, because every change is -confined to the repository's own build logic. +No dedicated wave is needed any more: the remaining seven pick the change up +with their next `./config/pull`, which rewrites their scripts. The default is +to let the next routine `refresh` wave +([`docs/rollout/rebuild.md`](../../docs/rollout/rebuild.md)) carry it. If it is +wanted sooner, plan a `refresh` wave scoped to the seven: one `--exclude` for +each other repository, and `--slug-suffix publish-api-docs`. ### Gates -- [ ] G1. The `config` PRs are merged. The first, config#814 ("Make the - `Publish` workflow reliable"), merged on 2026-10-22 as `ad3dff0890`. The - second, config#815 ("Publish API docs apart from Maven publishing"), is - open against `master`. Record its merge sha; it names the wave. -- [x] G2. The `config` session confirmed the names and the `migrate` deletions - on 2026-10-21, and added the third retired file, `Update.kt`, on - 2026-10-22. Re-check only if it reports a name change from review. -- [ ] G3. Wave `cascade-refresh-604420c` is closed (`cascade plan` refuses to - run over open `cascade-*` PRs). -- [ ] G4. The user says go. +- [x] G1. The `config` change is merged: config#815 as `58cd2d4a31`, and the + script rewrite, config#817, as `c5d6e5b2a5`, both on 2026-10-22. +- [x] G2. The names are final. +- [x] G3. Wave `cascade-refresh-604420c` is closed and archived. +- [ ] G4. The user says go, and chooses the next routine wave or a scoped one. ### Steps -- [ ] 1. Run `./cascade plan --kind refresh`, producing - `cascade-refresh-`. Review the order: 18 libraries in canonical - order, with `BuildSpeed` parked as usual. -- [ ] 2. For each repository, in wave order, run the cascade loop with one - insertion: `PREP:` (pull commit, pins, bump) → **hand edit** → - `BUILD:` → `PREPR:` → `SHIP:`. The hand edit has three parts: - 1. **Stale-file check.** After the pull, run - `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'`. Only the - consumer-owned files listed for the repository's group should match. A - hit in a config-owned path is a retired file that `migrate` missed. - Remove it with `git rm` if it is byte-identical to a blob `config` once - shipped at that path (check with `git -C config log --raw -- buildSrc`), - and commit as "Remove stale `buildSrc` files". - 2. **Group edit.** Apply the edit for the repository's group (A, B, or C), - and commit it as "Publish API docs separately from `publish`". Group D - repositories skip this part. - 3. **Proof.** Use dry runs only: on a release version, a real +- [ ] 1. Run `./cascade plan --kind refresh`, scoped or not, and review the + order. +- [ ] 2. In each of the seven, after `PREP:`: + 1. **Pull output.** The rewrite prints "Rewrote `` for + `publishApiDocs`" for each file it changes, and reports any use of the + old API it cannot rewrite. Fix a reported use by hand, in a commit of + its own. + 2. **Proof.** Use dry runs only: on a release version, a real `publishApiDocs` run pushes to `gh-pages`. Run the checks between wave builds, never alongside one. - `git grep -n -E 'updateGitHubPages|UpdateGitHubPages'` finds nothing. - `./gradlew publish -m` lists none of `publishApiDocs`, - `updateGitHubPages`, `copyJavadocDocs`, or `copyHtmlDocs`. + `copyJavadocDocs`, or `copyHtmlDocs`. - `./gradlew :publishAllApiDocs -m`, the task the workflow runs, plans the `publishApiDocs` task of each published module that is - documented. In `tool-base` and `change` this list is new. On a - snapshot version it lists no `copyJavadocDocs` or `copyHtmlDocs`, - because snapshots push no docs to `gh-pages`. + documented. On a snapshot version it lists no `copyJavadocDocs` or + `copyHtmlDocs`, because snapshots push no docs to `gh-pages`. - [ ] 3. Commit and PR rules: `cascade` makes its own `PREP` and `BUILD` commits. - The hand-edit commits and `SHIP` (push plus draft PR) happen only at the - user's explicit request (`AGENTS.md`). Post each PR link as it is opened. + A hand fix and `SHIP` (push plus draft PR) happen only at the user's + explicit request (`AGENTS.md`). Post each PR link as it is opened. - [ ] 4. After each merge, watch two runs: the repository's first `Publish` run, which must no longer touch the docs, and its first `publish-api-docs.yml` - run, which must end green. On a snapshot version, `PublishApiDocs` - registers a do-nothing task in place of the real one. That docs run - decrypts the deploy key in a workflow step, then logs for each documented - module that the docs are not published. It registers no SSH key, clones - nothing, and pushes nothing, so it proves only the decryption and the - task graph. A failed docs run does not block downstream repositories, - because the registry is unaffected, so fix it afterwards instead of - treating it as a failed publish. -- [ ] 4a. After the wave, on the first release version of any repository: watch - its `publish-api-docs.yml` run. It is the first real use of the sparse - `gh-pages` clone and push from config#815. Its commits read "Publish the + run, which must end green. On a snapshot version, that docs run decrypts + the deploy key and then logs, for each documented module, that the docs + are not published; it clones and pushes nothing. A failed docs run does + not block downstream repositories, because the registry is unaffected, so + fix it afterwards instead of treating it as a failed publish. +- [ ] 4a. On the first release version of any SDK repository, watch its + `publish-api-docs.yml` run. It is the first real use of the sparse + `gh-pages` clone and push from config#815; its commits read "Publish the `` documentation of the module …". Report a failure at the clone - or push step to the `config` session, or on config#815 if it has merged. + or push step on SpineEventEngine/config, citing config#815. - [ ] 5. Run `CLOSE` as usual. Then delete this file together with the wave's state pair. If step 4a is still open at that point, move it into the task file of the next release first. @@ -364,3 +204,9 @@ confined to the repository's own build logic. - 2026-10-22. A review asked to rename `delivery` to `delivery-server`, the name on `summit`'s `master`. Kept `delivery`, the current GitHub name, which summit#5 adopts, and added a note that maps the two names. +- 2026-11-04. Revised for config#817, which makes `./config/pull` rewrite the + consumer scripts. Eleven repositories already took the change in the + `cascade-refresh-604420c` wave or their own PRs; seven remain, and a dry run + of the rewrite shows no hand edit for them. Replaced the inventory with that + status, and the hand-edit steps with checks of the pull's output. Tightened + the context; G1–G3 are done. From ee0685b4ab49370cfd5f07fe2a96ae6a5ef6d888 Mon Sep 17 00:00:00 2001 From: alexander-yevsyukov Date: Thu, 5 Nov 2026 17:17:58 +0000 Subject: [PATCH 6/6] Record the closed API-docs wave in its plan Tick G4 and steps 1-4, log the scoped wave's PRs and the closing config#836, and keep the file open for step 4a, the first release version's docs run, until a release task file can take it over. Co-Authored-By: Claude Opus 5.5 --- .agents/tasks/publish-api-docs-wave.md | 54 +++++++++++++++++++------- 1 file changed, 40 insertions(+), 14 deletions(-) diff --git a/.agents/tasks/publish-api-docs-wave.md b/.agents/tasks/publish-api-docs-wave.md index b683d00..7a29e58 100644 --- a/.agents/tasks/publish-api-docs-wave.md +++ b/.agents/tasks/publish-api-docs-wave.md @@ -2,7 +2,7 @@ slug: publish-api-docs-wave branch: publish-api-docs-wave owner: claude -status: draft +status: in-progress started: 2026-10-21 --- @@ -54,20 +54,23 @@ into a skill. snapshots, so `gh-pages` stops changing until each one's next release; until now, every merge pushed its snapshot's docs. -## Status (2026-11-04) +## Status (2026-11-05) -Checked on each repository's `master`. +**Done: all 18 repositories.** The last seven took the change in the scoped wave +`cascade-refresh-1dbad1f-publish-api-docs`; see the Log. Only step 4a, the first +release version's docs run, is still open. -**Done: 11 repositories.** `tool-base`, `ProtoTap`, `compiler`, `validation`, -`core-jvm-compiler`, `time`, `money`, `core-jvm`, `jdbc-storage`, `gcloud-jvm`, -and `delivery` already pull a `config` with the split. Most got it in the -`cascade-refresh-604420c` wave, whose `./config/pull` took the latest `config` -`master` after 2026-10-22; the others in their own PRs. Each has +**Before the wave: 11 repositories.** `tool-base`, `ProtoTap`, `compiler`, +`validation`, `core-jvm-compiler`, `time`, `money`, `core-jvm`, `jdbc-storage`, +`gcloud-jvm`, and `delivery` already pull a `config` with the split. Most got it +in the `cascade-refresh-604420c` wave, whose `./config/pull` took the latest +`config` `master` after 2026-10-22; the others in their own PRs. Each has `PublishApiDocs.kt` and `publish-api-docs.yml`, no reference to the old names, and no `publish` dependency on the docs. Every `publish-api-docs.yml` run so far is green; all of them ran on snapshot versions, so they skipped the docs. -**Remaining: 7 repositories,** still on a `config` from before config#815. +**The wave: 7 repositories,** on a `config` from before config#815 as of +2026-11-04. | Repository | `config` pin | What the pull changes in the repository's own files | |------------------|--------------|---------------------------------------------------------| @@ -116,19 +119,23 @@ to let the next routine `refresh` wave wanted sooner, plan a `refresh` wave scoped to the seven: one `--exclude` for each other repository, and `--slug-suffix publish-api-docs`. +The user chose the scoped wave on 2026-11-04; it ran as +`cascade-refresh-1dbad1f-publish-api-docs`. + ### Gates - [x] G1. The `config` change is merged: config#815 as `58cd2d4a31`, and the script rewrite, config#817, as `c5d6e5b2a5`, both on 2026-10-22. - [x] G2. The names are final. - [x] G3. Wave `cascade-refresh-604420c` is closed and archived. -- [ ] G4. The user says go, and chooses the next routine wave or a scoped one. +- [x] G4. The user says go, and chooses the next routine wave or a scoped one: + a scoped wave, on 2026-11-04. ### Steps -- [ ] 1. Run `./cascade plan --kind refresh`, scoped or not, and review the +- [x] 1. Run `./cascade plan --kind refresh`, scoped or not, and review the order. -- [ ] 2. In each of the seven, after `PREP:`: +- [x] 2. In each of the seven, after `PREP:`: 1. **Pull output.** The rewrite prints "Rewrote `` for `publishApiDocs`" for each file it changes, and reports any use of the old API it cannot rewrite. Fix a reported use by hand, in a commit of @@ -143,10 +150,10 @@ each other repository, and `--slug-suffix publish-api-docs`. the `publishApiDocs` task of each published module that is documented. On a snapshot version it lists no `copyJavadocDocs` or `copyHtmlDocs`, because snapshots push no docs to `gh-pages`. -- [ ] 3. Commit and PR rules: `cascade` makes its own `PREP` and `BUILD` commits. +- [x] 3. Commit and PR rules: `cascade` makes its own `PREP` and `BUILD` commits. A hand fix and `SHIP` (push plus draft PR) happen only at the user's explicit request (`AGENTS.md`). Post each PR link as it is opened. -- [ ] 4. After each merge, watch two runs: the repository's first `Publish` run, +- [x] 4. After each merge, watch two runs: the repository's first `Publish` run, which must no longer touch the docs, and its first `publish-api-docs.yml` run, which must end green. On a snapshot version, that docs run decrypts the deploy key and then logs, for each documented module, that the docs @@ -161,6 +168,8 @@ each other repository, and `--slug-suffix publish-api-docs`. - [ ] 5. Run `CLOSE` as usual. Then delete this file together with the wave's state pair. If step 4a is still open at that point, move it into the task file of the next release first. + `CLOSE` ran (config#836, merged 2026-11-05). No release task file exists + yet, so this file stays, holding step 4a, until one does. ## Log @@ -210,3 +219,20 @@ each other repository, and `--slug-suffix publish-api-docs`. of the rewrite shows no hand edit for them. Replaced the inventory with that status, and the hand-edit steps with checks of the pull's output. Tightened the context; G1–G3 are done. +- 2026-11-04. The user chose a scoped wave, + `cascade-refresh-1dbad1f-publish-api-docs`, run from the main `summit` + checkout; G4 is done. +- 2026-11-05. The wave is closed. Its PRs: base-libraries#969 (`.463`), + reflect#17 (`.204`), logging#154 (`.429`), dokka-tools#14 (`.13`), + change#11 (`.210`), testlib#17 (`.217`), and base-types#58 (`.228`), all + `2.0.0-SNAPSHOT`; `CLOSE` landed as config#836. The rewrite reported nothing + and no old name remains. Two hand fixes, both outside the docs: + `base-libraries` and `testlib` force `Reflect.lib` on the buildscript + classpath, because `protobuf-setup-plugins` pulls an older `spine-reflect`; + `base-libraries`' `base` module makes `kspKotlin` and `kspTestKotlin` depend + on `generateProto` and `generateTestProto`. Every first `Publish` run is + green and no longer touches the docs. Every first docs run is green except + `base-libraries`', which failed before Gradle, at the runner's "Add swap + space" step (`pierotofy/set-swap-space` on the zram image + `ubuntu24/20261101.114`). Its re-run on 2026-11-05 (run 41925743501, + attempt 2) is green.