Skip to main content

release-docs.py

release-docs.py promotes documentation from the asf-staging branch to the asf-site branch, making it live on the production website.

What It Does​

The script:

  1. Checks that git is configured with the ASF committer identity
  2. Clones (or updates) a sibling ../asf-site/ checkout and fetches the asf-staging branch
  3. Switches to a detached HEAD at origin/asf-staging
  4. Force pushes to the asf-site branch

Usage​

Promote to Production​

python3 scripts/release-docs.py

⚠️ WARNING: This will make the documentation live on the production website.

Test Without Pushing​

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

Command-Line Options​

  • --no-push - Perform all steps except the final git push
  • --juneau-root DIR - Juneau source checkout whose juneau-terminal draws the live view (default: JUNEAU_ROOT, then a sibling ../master/, then a sibling ../juneau/)
  • --console full|board|none - Console output when the live view is available (default: JUNEAU_TERMINAL_CONSOLE, then board)

Live View​

When a Juneau checkout with juneau-terminal is found, the run is one live view with two rows: Prechecks (identity) and Promote (fetch, switch, and push, with the push shown as skipped under --no-push). Without juneau-terminal the script prints plain output.

Prerequisites​

  • Python 3.10 or higher
  • Git (git command must be in PATH)
  • Write access to the remote repository

Exit Codes​

  • 0 - Success
  • 1 - Error occurred

Notes​

  • The script uses a persistent sibling ../asf-site/ checkout for git operations, reused by later runs
  • If --no-push is used, the checkout is left at origin/asf-staging for manual inspection
  • A success sound is played when the script completes successfully
  • This script does NOT build documentation - it only promotes what's already in asf-staging

Workflow​

This script is typically used as the final step in the documentation release workflow:

  1. Make documentation changes
  2. Run release-docs-stage.py to deploy to staging
  3. Review the staging site at https://juneau.staged.apache.org
  4. Run release-docs.py to promote to production at https://juneau.apache.org

Safety​

The script includes a warning message before promoting to production to ensure you understand the impact.