release-docs.py

Promotes the staged documentation (asf-staging branch) to production by force-pushing it to the asf-site branch.

When to use

  • The staged site at http://juneau.staged.apache.org looks right and should go live.
  • To put a new build on staging first, use release-docs-stage.py.
  • To rehearse everything except the final push, use --no-push.

Usage

python3 scripts/release-docs.py --no-push
python3 scripts/release-docs.py

Run from the docs checkout. The second form makes the staged site live.

Options

OptionArgumentDefaultMeaning
--no-pushnoneoffDo everything except the final git push.
--commit-messagetextnoneAccepted for consistency with release-docs-stage.py; not used.
--juneau-rootdirectory$JUNEAU_ROOT, then ../master, then ../juneauJuneau checkout whose juneau-terminal draws the live view. Not validated.
--consolefull, board, noneboardConsole output when juneau-terminal is available; also JUNEAU_TERMINAL_CONSOLE (the flag wins).

What it does

  1. Prechecks (promote): git user.email must be the ASF committer identity jamesbognar@apache.org; the script cannot change git config and prints the commands to run.
  2. Reads the remote.origin.url of the repository it is run from, and requires the parent of the docs checkout to exist.
  3. Fetch: updates the persistent sibling checkout ../asf-site (or clones the remote there, removing a directory that is not a git repository), then fetches asf-staging.
  4. Switch: git switch --detach origin/asf-staging in that checkout, and copies the current git user.name and user.email into it.
  5. Push: git push origin HEAD:asf-site --force. Skipped with --no-push; the manual command is then printed.
  6. Plays a success sound when the exit code is 0.

Output and exit codes

Progress is the juneau-terminal live view (rows Prechecks and Promote) or plain text with a warning that the site will go live. Nothing is built or committed; the pushed commit is whatever asf-staging points to.

CodeMeaning
0Promoted (or --no-push rehearsal completed).
1The identity precheck failed, the remote URL or parent directory was missing, a git step failed, or the run was interrupted.

Gotchas

  • This changes the live production site. The push is a force push.
  • The remote URL is read from the current directory's repository, so run it from inside the docs checkout.
  • ../asf-site is a persistent checkout reused between runs.
  • --help prints the module docstring as an epilog.

See also

  • release-docs-stage.py, build-docs.py
  • Docs site: Developer Info, Script: release-docs (pages/developer-info/04.03.02.ScriptReleaseDocs.md)