blob: eb22e41580d07959fcc827d07b55b7ec90b63bd3 [file] [view]
# push.py
Builds, tests, commits and pushes Juneau (and, when present, the sibling juneau-docs repository) in one command.
## When to use
- You have staged your reviewed changes and want them verified and pushed to the tracked upstream.
- You want only the build and test gates, with no commit or push: use `--test-only`.
- You changed only juneau-docs: use `--docs-only`.
- To run just the tests, use `test.py` directly instead.
## Usage
```bash
python3 scripts/push.py "Fixed bug in RestClient"
python3 scripts/push.py "Updated topic page" --docs-only
python3 scripts/push.py --test-only
python3 scripts/push.py "Fix a test" --warn-traces
python3 scripts/push.py "Quick fix" --skip-tests --dry-run
```
The commit message is optional on the command line. It is prompted for when omitted, except with `--test-only`.
## Options
| Option | Argument | Default | Meaning |
|---|---|---|---|
| `message` | text (optional positional) | prompted | Git commit message. An empty or missing message aborts with exit 1 (`resolve_commit_message`). |
| `--test-only` | none | off | Run only the build and test gates. No identity check, commit, push or juneau-docs follow-up. Cannot be combined with `--docs-only`, `--tracker-audit` or `--skip-tests`. |
| `--skip-tests` | none | off | Skip the test step. The build then runs `mvn clean package install -DskipTests`. |
| `--dry-run` | none | off | Print the steps that would run and exit 0. |
| `--docs-only` | none | off | Operate only on juneau-docs: skip all Juneau build, test, commit and push steps. The identity and docs-verification gates still run. `--skip-tests` is ignored with a note. |
| `--tracker-audit`, `--todo-audit` | none | off | Opt-in gate for maintainers who keep an external work-tracker checkout: blocks the push if its audit flags a file. |
| `--js-tests` | none | auto | Force the headless-browser JS harness. Fails if Node or npm is missing. Mutually exclusive with `--no-js-tests`. |
| `--no-js-tests` | none | off | Never run the JS harness, even when JS, CSS or FTL files changed. |
| `--warn-traces` | none | off | Report stack traces in the test output as a warning instead of failing the Traces row. Allowlist errors still fail. |
| `--console` | `full`, `board`, `none` | `board` | Maven output on the console. Also `JUNEAU_TERMINAL_CONSOLE`; the flag wins. |
| `--detail` | `summary`, `actionable`, `modules`, `all` | `actionable` | Console detail. Also `JUNEAU_TERMINAL_DETAIL`. |
## What it does
1. Parses and validates the arguments. A bad combination exits 2 (`parse_args`).
2. Prechecks, before any build work (`prechecks`): git `user.email` is the committer identity the script requires (`REQUIRED_GIT_EMAIL`), the tree has no unstaged or untracked-and-not-ignored changes, the branch is not behind its upstream, and every `.github/workflows/*.yml` / `*.yaml` parses as YAML (PyYAML; the refusal names `file:line:col`). The first three run for juneau-docs when it is present and has staged changes or unpushed commits.
3. Optional gate, when asked: tracker audit (`run_tracker_audit_gate`).
4. Unless `--skip-tests`: `check-container-tags.py`, `check-bom-completeness.py`, then `test.py --full` (which builds, installs and runs the Java, Python and, when needed, browser tests, then fails on any stack trace they printed that [`trace-allowlist.txt`](trace-allowlist.txt) does not allow), then `push-timings.py`.
5. Commits whatever is already staged and pushes to the tracked upstream (`commit_and_push`). It stages nothing itself.
6. Repeats the follow-up for juneau-docs when it exists (`run_docs_followup`), after its docs build check.
## Output and exit codes
Progress is a board view. Full logs go under `~/.cache/juneau-terminal/`, and the session header prints the `tail -f` line for the log. Test timings are appended to `~/.cache/juneau-terminal/history/<repo>-<sha8>/test.jsonl`.
The commit and push steps run under a PTY with a 20-second watchdog. If git goes silent after a partial line, such as an ssh passphrase or pinentry prompt, that line appears on the board as a prompt. Type the answer as usual.
| Code | Meaning |
|---|---|
| 0 | Pushed, nothing to push, `--dry-run`, `--test-only` passed, or `--docs-only` with no changes. |
| 1 | A gate failed, the prechecks refused (including invalid workflow YAML or PyYAML missing), or no commit message was given. |
| 2 | Invalid argument combination. |
| 130 | Cancelled with Ctrl-C or, with run markers on, SIGTERM. |
## Gotchas
- It never stages for you. Anything unstaged or untracked-and-not-ignored makes the prechecks refuse, and the check repeats just before the commit.
- The workflow-YAML guard needs PyYAML whenever the repo has workflow files, and fails closed without it: `pip install pyyaml`, or run the script with `uv run --with pyyaml`. The check repeats just before the commit, and also for a push-only run.
- The commit takes the index exactly as it finds it, so stage the whole set you want pushed.
- `JUNEAU_PUSH_NO_SOUND` silences the completion sound.
- `--test-only` here means "gates without a commit or push". `test.py --test-only` means "tests without the build".
- The upstream check does a `git fetch`, so it needs the network. A failed fetch fails closed.
## See also
- `test.py`, `push-timings.py`, `check-container-tags.py`, `check-bom-completeness.py`
- Docs site: Developer Info, Script: push (`04.02.02.ScriptPush.md` in juneau-docs)