blob: a278b878e0261f7221d9fe3c53cf4c98508abeb2 [file] [view]
# 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
```bash
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
| Option | Argument | Default | Meaning |
|---|---|---|---|
| `--no-push` | none | off | Do everything except the final `git push`. |
| `--commit-message` | text | none | Accepted for consistency with `release-docs-stage.py`; not used. |
| `--juneau-root` | directory | `$JUNEAU_ROOT`, then `../master`, then `../juneau` | Juneau checkout whose `juneau-terminal` draws the live view. Not validated. |
| `--console` | `full`, `board`, `none` | `board` | Console 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.
| Code | Meaning |
|---|---|
| 0 | Promoted (or `--no-push` rehearsal completed). |
| 1 | The 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`)