push.py

push.py runs Juneau's build and test gates and then commits and pushes what you have staged. It never stages anything: the index is the record of what you have reviewed, so the script commits the index exactly as it finds it and refuses to run while anything in the tree is unstaged or untracked. It runs on juneau-terminal, which draws its rows and keeps its logs and timing history.

What It Does

Each step is a row in the console view. In order:

Row	What it does
Prechecks	Refuses before any gate unless git's user.email is the ASF committer address, the tree has no unreviewed changes, and the branch isn't behind its upstream (git fetch, then compare; no upstream passes, and a failed fetch refuses). When the sibling juneau-docs has something staged or unpushed commits, the same three checks run there too.
Tracker	Only with --tracker-audit. See Optional gates.
Tags	scripts/check-container-tags.py: every test class that boots a container uses @SpringbootTest, @JettyMicroserviceTest or @TomcatMicroserviceTest.
BOM	scripts/check-bom-completeness.py: juneau-bom lists every consumer-facing module.
Compile	test.py --full's mvn clean install -DskipTests build.
Java tests	test.py's Maven test run. test.py adds its Perf row after it.
Python tests	test.py's run of scripts/tests, the tooling's own pytest suite.
Browser tests	test.py's *_BrowserTest run under -Pjs-tests. See Browser tests.
Traces	test.py's stack-trace guard: fails the push on any stack trace in the test output that scripts/trace-allowlist.txt does not allow. See test.py.
Timing	scripts/push-timings.py: compares this run's timings with the run history and writes the full table to test-timings.txt beside it. Advisory only; it never stops the push.
Install	Skipped, because test.py --full has already installed. With --skip-tests it runs mvn clean package install -DskipTests.
Commit	git commit -m <message> on the index as staged. Skipped when nothing is staged.
Push	git push to the branch's tracked upstream.
Docs build, Docs, Docs push	The juneau-docs follow-up.

Tags through Timing are the test step; --skip-tests replaces them with one skipped Java tests row. A failed row stops the run, and nothing after it runs.

Reviewed Changes Only

Stage each file as you review it, then run push.py. Just before it commits, the script checks the tree again:

• Something unstaged or untracked: it refuses and commits and pushes nothing, not even the staged part. Untracked files that git ignores don't count. The refusal lists the paths and the commands to set them aside for the run: git stash push -- <paths>, then git stash pop afterwards. There is no override flag.
• Nothing staged, but unpushed commits: it skips the commit and pushes those commits.
• Nothing staged and nothing to push: it says so and exits 0.
• Behind the upstream: it refuses. The upstream is checked again here because it can move during the build.

juneau-docs Follow-Up

When a juneau-docs checkout sits beside juneau, a successful juneau push is followed by the same commit and push in juneau-docs, with the same commit message:

1. Docs build runs scripts/build-docs.py --skip-maven there (a Docusaurus build, which runs verify-docs.py, check-project-pages.py and check-entry-pages.py), only when something is staged.
2. Docs commits the juneau-docs index as staged.
3. Docs push pushes it, or pushes earlier unpushed commits when nothing is staged.

The same rules apply there: an unstaged or untracked file in juneau-docs refuses the follow-up. Prechecks cover juneau-docs only when it has something staged or unpushed, so an idle juneau-docs with stray edits doesn't block a juneau push. If it becomes active during the build, its identity is checked just before its commit.

The follow-up runs only after juneau itself committed or pushed something. To push juneau-docs on its own, use --docs-only.

Usage

cd /path/to/juneau
python3 scripts/push.py "Your commit message here"

Without a message, the script asks for one; an empty answer aborts.

python3 scripts/push.py "Updated README" --skip-tests     # no test step; Install builds instead
python3 scripts/push.py "Testing changes" --dry-run       # list the steps and evaluate the Prechecks only
python3 scripts/push.py --test-only                       # gates only; no commit or push
python3 scripts/push.py "Updated topic page" --docs-only  # juneau-docs only

Command-Line Options

Option	Effect
message	The commit message. Prompted for when omitted. Not used with --test-only.
--test-only	Runs only the build and test gates (Tags, BOM, the test step and Install). No Prechecks, commit, push or juneau-docs follow-up. Not the same as test.py --test-only, which means tests without the build. Can't be combined with --docs-only, --tracker-audit or --skip-tests.
--skip-tests	Skips the test step (Tags through Timing). Install then runs mvn clean package install -DskipTests.
--dry-run	Prints the steps that would run and evaluates the Prechecks, then exits without building, committing or pushing.
--docs-only	Works on the sibling juneau-docs only: Prechecks there, then Docs build, Commit and Push. Skips everything on the juneau side, so --skip-tests is ignored. Exits 0 when juneau-docs has nothing to commit or push.
--js-tests	Forces the Browser tests. Fails the push if Node or npm is missing.
--no-js-tests	Never runs the Browser tests. Can't be combined with --js-tests.
--warn-traces	Reports stack traces in the test output as a warning instead of failing the Traces row.
--console full|board|none	The console view. Default board; also JUNEAU_TERMINAL_CONSOLE, and the flag wins. See Console view.
--detail summary|actionable|modules|all	How many sub-rows a finished row keeps. Default actionable; also JUNEAU_TERMINAL_DETAIL.
--tracker-audit, --todo-audit	Adds the Tracker gate.

Browser Tests

With neither --js-tests nor --no-js-tests, test.py decides: it runs the Browser tests when a .js, .cjs, .css or .ftl file under a src/ tree differs from origin/master, and otherwise marks the row skipped. If Node or npm is missing, an automatic run is skipped with a notice. push.py passes either flag through to test.py.

Optional Gates

It runs right after the Prechecks, before any build, so it fails fast.

• Tracker (--tracker-audit) runs a maintainer's local work-tracker audit (~/Project Work/scripts/todo-status-audit.py) and blocks the push if it flags a plan file. It is a local check with no network access, and it fails when that tracker isn't present.

Requirements

• Python 3, and the juneau-terminal sources in the checkout (juneau-terminal/src/main/python/), which the script loads directly.
• Maven and Git on the PATH.
• Node and npm for the Browser tests.
• git's user.email set to the ASF committer address in juneau (and in juneau-docs when it is pushed). The script never writes git config; the refusal prints the command to run.

Exit Codes

• 0 - Success, including a run with nothing to commit or push.
• 1 - A precheck, gate, build, test, commit or push failed.
• 2 - Invalid options.
• 130 - Cancelled with Ctrl-C or SIGTERM.

See Also

• test.py
• juneau-terminal
• Scripts