Scripts
Apache Juneau includes a collection of Python scripts in the scripts/ directory that automate various development, build, test, and release tasks. These scripts help maintain code quality, streamline workflows, and ensure consistency across the project.
Available Scripts
Scripts are organized into two categories based on which branch/repo checkout they're located in. This index covers the most commonly-used developer scripts; a handful of narrowly-scoped or CI-internal scripts are listed without dedicated pages.
4.2. Code Scripts (master branch)
These scripts are located in the master branch (the juneau repository/checkout) and are used for code development, testing, and releases:
| Script | Description | Details |
|---|---|---|
| test.py | Build and test helper script | Learn more → |
| push.py | Build, test, and push to repository | Learn more → |
| release.py | Complete release automation | Learn more → |
| prompt-pgp-passphrase.py | Prompt for PGP passphrase early | Learn more → |
| current-release.py | Get current release version | Learn more → |
| maven-version.py | Get Maven version | Learn more → |
| apply-eclipse-prefs.py | Apply Eclipse preferences | Learn more → |
| cleanup-whitespace.py | Clean up whitespace in Java files | Learn more → |
| check-fluent-setter-overrides.py | Check fluent setter overrides | Learn more → |
| revert-staged.py | Revert staged git changes | Learn more → |
| revert-unstaged.py | Revert unstaged git changes | Learn more → |
| start-petstore-jetty.py | Start the petstore showcase under Jetty/Microservice | Learn more → |
| start-petstore-springboot.py | Start the petstore showcase under Spring Boot | Learn more → |
check-bom-completeness.py | Verifies the published juneau-bom lists all reactor modules | — |
check-container-tags.py | Guardrail that verifies container-backed tests are tagged correctly | — |
ci-perf-guard.py | CI wall-clock performance regression guard, per module/bucket | — |
coverage.py | Generates and reports JaCoCo test coverage | — |
microbench.py | Runs JMH micro-benchmarks | — |
normalize-generic-commas.py | Normalizes comma spacing in generic type arguments | — |
push-timings.py | Reports timing deltas from test.py's run history (the push.py Timing row) | — |
slack-notify.py | Sends build/release notifications to Slack | — |
surefire-rollup.py | Rolls up Surefire XML results into per-module/bucket timing summaries | — |
4.3. Doc Scripts (docs branch)
These scripts are located in the docs branch (the juneau-docs repository/checkout) and are used for documentation building, validation, and deployment:
| Script | Description | Details |
|---|---|---|
verify-docs.py | Docs integrity checker - validates frontmatter, slugs, sidebar structure, and internal links; the primary "does the site check out?" gate | See check-topic-links.py for a related, narrower link-only check |
| release-docs-stage.py | Stage documentation to asf-staging | Learn more → |
| release-docs.py | Promote documentation to production | Learn more → |
| build-docs.py | Build complete documentation | Learn more → |
| create-mvn-site.py | Generate Maven site for testing | Learn more → |
| start-docusaurus.py | Start Docusaurus dev server | Learn more → |
| check-topic-links.py | Validate documentation links | Learn more → |
check-guide-snippets.py | Checks that every code block on a guide page matches its tested region in the Juneau checkout's juneau-examples-guides module | See AI Knowledge Authoring ("Guide Fences") |
check-project-pages.py | Checks that the About pages under src/pages/about/ match src/data/projects.ts | Run by build-docs.py in its Verify stage |
check-entry-pages.py | Checks that the entry pages agree: one format count tied to the marshaller classes, one first resource, the documented ports, no unsupported comparison claims | Run by build-docs.py in its Verify stage |
| generate-ai-artifacts.py / check-ai-artifacts.py | Generate and validate machine-consumable AI knowledge artifacts | Learn more → |
apply-renames.py | Bulk URL/text substitution pass across pages/, driven by a rules table (--table, --dry-run) | — |
check-topic-template.py | Advisory report of topic pages that drift from the topic page template: stubs, pages with no code fence, headings out of order | — |
renumber-topics.py | Renames pages/topics files gap-free in sidebar order, rewriting front-matter ids, sidebars.ts ids and references to match (dry run unless --apply); sidebar numbers are generated and untouched | — |
normalize-headings.py | Normalizes Markdown heading structure under pages/topics/ | — |
Note: verify-docs.py is the primary docs-integrity gate - run python3 scripts/verify-docs.py --strict --anchors from the juneau-docs repository root before publishing any documentation change. See the script's --help output for the full list of checks and flags.
Common Features
All scripts share the following characteristics:
- Python 3.6+ - Written in Python using only the standard library
- No External Dependencies - All scripts use only Python standard library modules
- Cross-Platform - Work on macOS, Linux, and Windows
- Error Handling - Provide clear error messages and exit codes
- Documentation - Each script has detailed documentation in the Docusaurus topics
Getting Help
Each script supports a --help flag to display usage information:
python3 scripts/<script-name>.py --help
For detailed documentation, see the individual script topic pages linked above.
Requirements
Most scripts require:
- Python 3.6 or higher
- Maven (for build/test/release scripts)
- Git (for version control scripts)
- Node.js and npm (for documentation scripts)
Specific requirements are documented in each script's topic page.