push.py

Gates, commits and pushes the docs branch of juneau-docs, then stages the same build to asf-staging.

When to use

  • You have staged your reviewed docs changes and want them checked, pushed and previewed on http://juneau.staged.apache.org in one command (push juneau-docs).
  • You want the checks and the push without a deploy: use --no-stage.
  • To make staging live, run release-docs.py afterwards. This script never does.

Usage

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.

Options

OptionArgumentDefaultMeaning
messagetext (optional positional)promptedGit commit message for docs. An empty message aborts with exit 1.
--no-stagenoneoffGate, commit and push only. The build runs with --skip-maven (no Maven site, so no Juneau build) and nothing is staged.
--dry-runnoneoffPrint the steps and run the Prechecks. Nothing is built, committed or pushed.
--stage-messagetextDeploy documentation stagingCommit message for the asf-staging commit.
--juneau-rootdirectory$JUNEAU_ROOT, then ../master, then ../juneauJuneau source checkout, for the Maven site, the sibling-checkout checks and the juneau-terminal view. Required for a staged push.
--consolefull, board, noneboardConsole output when the Juneau checkout provides juneau-terminal; also JUNEAU_TERMINAL_CONSOLE (the flag wins). Passed on to build-docs.py.

What it does

  1. Prechecks (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.
  2. AI artifacts (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.
  3. Build and checks: runs 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.
  4. Commit: commits the index exactly as found (git commit), which includes the step 2 files and the step 3 javadocs. It stages nothing else. With nothing staged the row is skipped.
  5. Push: git push to the upstream, when there is a new commit or unpushed commits.
  6. Stage: unless --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.

Output and exit codes

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.

CodeMeaning
0Pushed (and staged unless --no-stage), or --dry-run finished with passing Prechecks.
1A precheck, the build or a check failed, or a git step failed. Nothing is committed when a gate fails.
130Cancelled with Ctrl-C.

Gotchas

  • The Maven steps inside its 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.
  • Everything outward-facing happens here: it pushes docs and force-pushes asf-staging. Run it only when you mean to.
  • It refuses on any unstaged or untracked file. Stage what you have reviewed, or git stash push -- <paths> the rest.
  • A staged push runs the full Maven build of the Juneau checkout (slow); --no-stage avoids it.
  • The checks run before the commit, so a failed check leaves your staged work untouched (the regenerated AI artifacts and javadocs this run staged are unstaged again).
  • release-docs.py (production) is never called.

See also

  • build-docs.py, release-docs-stage.py, release-docs.py
  • Juneau's scripts/push.py, which no longer touches juneau-docs; it prints a hint to run this script.