[alexander-yevsyukov]

Problem

#815 renamed the UpdateGitHubPages plugin to PublishApiDocs, with no deprecated aliases. migrate deletes the stale plugin sources, but it restores the consumer's own buildSrc/src/main/kotlin/module.gradle.kts, and most consumers call the old API there. After ./config/pull, their buildSrc stops compiling:

e: module.gradle.kts:36:37 Unresolved reference 'updateGitHubPages'.
e: module.gradle.kts:153:5 Unresolved reference 'updateGitHubPages'.
e: module.gradle.kts:154:9 Unresolved reference 'rootFolder'.

The summit wave hit this re-shipping time, which got a fix by hand (SpineEventEngine/time#202, commit 54c0e602). The other consumers still on config ad3dff08 hit it on their next pull.

Change

scripts/migrate-publish-api-docs.sh, called by migrate, rewrites the consumer's own scripts that name the old API: the Kotlin sources and scripts under buildSrc/src, and the tracked *.gradle.kts files elsewhere. The files config distributes no longer name it, so what is found belongs to the consumer.

• import io.spine.gradle.github.pages.updateGitHubPages → …publishApiDocs.
• updateGitHubPages { and updateGitHubPages() { → publishApiDocs {.
• The dependency of publish on the docs task is deleted, in both known forms: tasks.named("publish") { dependsOn("${project.path}:updateGitHubPages") }, and project.afterEvaluate { val publish = tasks.findByName("publish"); publish?.dependsOn(…) }. Kept, it would fail publish on a task that no longer exists. It is not renamed either, because the docs are no longer a part of publish.
• A script's own fun Module.configureGitHubPages() and its calls become configureApiDocs(), with the KDoc of jvm-module.gradle.kts when the function has none. A script's top-level functions are visible only inside the script, so every call is in that file.

Each rewrite matches only the old form, so a second run changes nothing. A file is written only when its content changes, and it keeps its mode and CRLF line endings.

Any use of the old API left afterwards, and any tracked workflow that names the old task, is a form the script does not know. It prints a warning with the file, the line, and the replacements. migrate stays fail-open: if the script fails, the pull goes on with a warning.

The script runs after the workflows are copied, so the warning covers only the workflows the consumer keeps itself. The closing git add ./buildSrc/src stages the rewritten buildSrc files. A rewritten script outside buildSrc, such as gcloud-jvm's root build.gradle.kts, is left unstaged for the developer to commit.

Swap space for publish-api-docs.yml

The third commit addresses a Codex finding on SpineEventEngine/time#202 about the distributed publish-api-docs.yml. For a release version, :publishAllApiDocs runs Dokka for every published module, and org.gradle.parallel=true lets those runs overlap. Hosted Linux runners have effectively no swap, so a memory peak becomes an OOM kill. build-on-ubuntu.yml already adds 8 GB of swap for that reason, so the docs job now gets the same pierotofy/set-swap-space@v1.0 step. The step runs before the deploy key is decrypted, so the third-party action never runs while the key is on disk. A snapshot version is unaffected either way: its publishApiDocs runs no Dokka. actionlint reports only the concurrency.queue key that #815 already accepted.

Survey

I checked consumer-owned files on origin/master of the 19 Gradle repositories in summit (the per-form table is in .agents/tasks/migrate-publish-api-docs.md). The old API appears in 12 module.gradle.kts files and in gcloud-jvm's root build.gradle.kts. All 13 use the forms above. On copies of all 13, the script rewrote every use and printed no warnings.

Verification

• Same as the hand fix. For time, the rewritten module.gradle.kts is byte-identical to 54c0e602.

• Compiles against config master. For time, compiler, testlib, tool-base, change, and core-jvm:

  1. I unpacked origin/master with git archive, added this branch as config/ (with adopt-shared-agents stubbed), and ran the real migrate. No use of the old API was left, and module.gradle.kts was staged.
  2. With a minimal root project, ./gradlew help built buildSrc: BUILD SUCCESSFUL for all six. :buildSrc:compileKotlin ran each time rather than coming from the cache, and produced Module_gradle.class.

• Negative control. The same layout with compiler's unmigrated module.gradle.kts fails with the errors quoted above.

• scripts/test-migrate-publish-api-docs.sh: 43 checks pass. It covers:

  • each surveyed form against its expected text (the afterEvaluate one is time's fix);
  • a top-level call in a second buildSrc script, a tracked root script, and a tracked script under a non-ASCII path;
  • CRLF line endings and mode 644;
  • forms the script does not know, which are left as they are and reported by line: a dependsOn with more than the docs task, a declaration of updateGitHubPages() (with an annotation before it, too), the extension type, and a workflow's -x updateGitHubPages;
  • a function's own KDoc (kept), and the added KDoc compared against jvm-module.gradle.kts;
  • untracked scripts (ignored), and a consumer outside Git (only buildSrc is rewritten);
  • a script holding nothing but the docs dependency, which is left empty, whether it is rewritten first or after another file;
  • a second run (no changes);
  • the real migrate, which rewrites and stages the restored module.gradle.kts and stages the deleted plugin source.

  Reverting any of the guards one at a time makes the suite fail: the afterEvaluate rule, the single-argument dependsOn match, ls-files -z, the declaration check, and the emptied temporary output.

• The other migrate suites (test-migrate-ide-files, test-migrate-publishing-pin, test-migrate-wrapper-validation, test-update-gitignore) pass, and the JVM fixtures of the pin and wrapper-validation suites now carry the new script. shellcheck is clean on migrate and on every changed script.

• spine-code-review and review-docs both approved with changes, and the changes are applied in the second commit. Two later findings from the PR review (Codex: an annotated declaration; Copilot: stale temporary output when a rewrite drops every line) are fixed in the fourth. spine-code-review ran the script under BSD awk, mawk 1.3.4, and gawk 5.3.2 and got byte-identical results. After the changes, the 13 real files still rewrite to the same output.

• ./gradlew detekt passes, and ./gradlew -p buildSrc test passes all 315 tests. No Kotlin changed.

Not covered

• The publish dependency removal is checked against the expected text, not by running publish --dry-run in a full consumer build.
• gcloud-jvm's root build.gradle.kts is checked against the expected text and against the same form in the tests. It was not compiled, since that would configure the whole gcloud-jvm build.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-22T20:07:20.169576Z	0faf747	New commits

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 54cdcf578a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

🟡 Changes recommended

A verified temporary-output reuse bug can overwrite a consumer script with another script’s contents when its rewrite removes every line.

1 open issue

• Initialize temporary output before each AWK rewrite · New

What changed in this PR

This PR automates consumer migration to publishApiDocs during config pulls, following the separation of API documentation publishing from Maven publishing.

Changes:

• Rewrite known legacy Gradle API calls, remove old publishing dependencies, and warn about unsupported forms.
• Add migration regression coverage and update existing test fixtures.
• Add 8 GB of swap to the API documentation workflow before deploy-key decryption.

File	Description
scripts/​test-migrate-wrapper-validation.sh	Include the new migration script in fixtures.
scripts/​test-migrate-publishing-pin.sh	Include the new migration script in fixtures.
scripts/​test-migrate-publish-api-docs.sh	Add rewrite, preservation, warning, and integration checks.
scripts/​migrate-publish-api-docs.sh	Implement legacy API migration and remaining-use warnings.
migrate	Invoke the migration after workflow copying.
.github-workflows/​publish-api-docs.yml	Allocate swap for parallel documentation builds.
.agents/​tasks/​migrate-publish-api-docs.md	Record the consumer survey, implementation, and verification.

_{Review effort: Balanced}

[Copilot]

🟢 Approved

The supported migration forms have targeted regression coverage, the earlier temporary-output issue is fixed, and no blocking findings remain.

No open issues 🎉

1 resolved since last review

• Initialize temporary output before each AWK rewrite

_{Review effort: Balanced}