Gates, commits and pushes the docs branch of juneau-docs, then stages the same build to asf-staging.
push juneau-docs).--no-stage.release-docs.py afterwards. This script never does.python3 scripts/push.py "Rewrote the REST client topic" python3 scripts/push.py "Fix a typo" --no-stage python3 scripts/push.py "Stage with a note" --stage-message "Stage docs for 10.0.0" python3 scripts/push.py "Try it" --dry-run
Run from the docs checkout. The commit message is prompted for when omitted.
| Option | Argument | Default | Meaning |
|---|---|---|---|
message | text (optional positional) | prompted | Git commit message for docs. An empty message aborts with exit 1. |
--no-stage | none | off | Gate, commit and push only. The build runs with --skip-maven (no Maven site, so no Juneau build) and nothing is staged. |
--dry-run | none | off | Print the steps and run the Prechecks. Nothing is built, committed or pushed. |
--stage-message | text | Deploy documentation staging | Commit message for the asf-staging commit. |
--juneau-root | directory | $JUNEAU_ROOT, then ../master, then ../juneau | Juneau source checkout, for the Maven site, the sibling-checkout checks and the juneau-terminal view. Required for a staged push. |
--console | full, board, none | board | Console output when the Juneau checkout provides juneau-terminal; also JUNEAU_TERMINAL_CONSOLE (the flag wins). Passed on to build-docs.py. |
precheck_list): git user.email is jamesbognar@apache.org; the branch is docs; no unstaged or untracked-and-not-ignored file (unreviewed_problem); the branch has an upstream and is not behind it.regenerate_ai_artifacts), once the Prechecks (including the unreviewed-changes refusal) pass: runs check-ai-artifacts.py --juneau-root <checkout>; when the generated static/llms.txt / static/ai/ are stale, runs generate-ai-artifacts.py, prints the files it rewrote and stages exactly those paths. This is the one thing the script stages, and the test is provenance: only this run's own generator output, taken as the paths that were unstaged or untracked after the refusal guard found none. It refuses (nothing staged, exit 1) when the generator wrote anything outside static/llms.txt and static/ai/, when the artifacts are still stale afterwards, or when you had already staged one of those paths. When the run fails before the commit (or is interrupted), it unstages exactly the paths it staged (git restore --staged); the files stay on disk. With no Juneau checkout the row is skipped.build-docs.py --staging (or --skip-maven with --no-stage). build-docs.py is the single list of checks: verify-docs, check-project-pages, check-entry-pages, check-doc-inventory, check-topic-links, check-ai-artifacts, check-code-fences, check-java-fences and check-guide-snippets, then the Docusaurus build. The sibling-checkout checks run whenever the Juneau checkout exists. The check-ai-artifacts step passes here because step 2 regenerated the artifacts. The build copies fresh javadocs into static/javadocs/<version>/; stage_built_javadocs then stages exactly the new, modified or deleted paths under static/javadocs/ (same provenance as step 2: the refusal guard passed before the build, so every unstaged or untracked path afterwards is build output) and prints “Staged N regenerated javadoc file(s) for this commit.” so the javadocs ship in the same commit rather than lagging a push behind. A path you had already staged is re-added but stays staged if the run fails; only paths this run newly staged are unstaged on failure. Any other tracked file the build rewrites (artifact maps, the javadoc index) only produces a warning and is not committed.git commit), which includes the step 2 files and the step 3 javadocs. It stages nothing else. With nothing staged the row is skipped.git push to the upstream, when there is a new commit or unpushed commits.--no-stage, release-docs-stage.py's publish_build stages the build from step 3 (no second build): fetch ../asf-staging, copy build/, commit, force-push asf-staging, open the URL. The staged commit is printed at the end.Progress is the juneau-terminal live view (Prechecks, AI artifacts, the build rows, Commit, Push, Stage push, URL) or plain text when that is unavailable.
| Code | Meaning |
|---|---|
| 0 | Pushed (and staged unless --no-stage), or --dry-run finished with passing Prechecks. |
| 1 | A precheck, the build or a check failed, or a git step failed. Nothing is committed when a gate fails. |
| 130 | Cancelled with Ctrl-C. |
build-docs.py run wait for the shared Maven lock (see build-docs.md), so starting this together with push.py in the Juneau checkout is safe: the second waits for the first's Maven span.docs and force-pushes asf-staging. Run it only when you mean to.git stash push -- <paths> the rest.--no-stage avoids it.release-docs.py (production) is never called.build-docs.py, release-docs-stage.py, release-docs.pyscripts/push.py, which no longer touches juneau-docs; it prints a hint to run this script.