Publish to Homebrew

[kaklakariada]

Plan: Publish OpenFastTrace in Homebrew Core

Publish OpenFastTrace directly to Homebrew/homebrew-core as a formula that installs the released portable JAR and exposes its oft CLI through Homebrew's Java 17 launcher. Reuse the existing GitHub-release JAR and its SHA-256 checksum. Once accepted, rely on Homebrew/core's default autobump service to create version-update pull requests; do not add cross-repository credentials or formula-update automation to the OpenFastTrace release workflow.

Steps

1. Prepare the first core contribution. Fork Homebrew/homebrew-core, tap it locally, and create an openfasttrace formula branch from its current default branch. Confirm no newly merged or pending formula conflicts with the intended openfasttrace name before making the contribution. This blocks all following core work.

2. Author the core-ready formula. Add Formula/o/openfasttrace.rb in the Homebrew/core fork with OpenFastTrace's GitHub repository as its homepage, GPL-3.0-only SPDX identifier, immutable GitHub Release JAR URL, and the SHA-256 value from the attached openfasttrace-<version>.jar.sha256 release asset. Declare openjdk@17 as the runtime dependency, install the exact versioned JAR into libexec, and expose only the oft command using Homebrew's write_jar_script helper pinned to Java 17. Do not build from the Maven source archive: the release JAR is portable, is the artifact users run today, and is an allowed output under Homebrew/core policy.

3. Add a real formula smoke test. In the formula's test do block, create a small valid Markdown trace fixture under Homebrew's temporary testpath, run oft trace against it, and assert the successful report/output. Model the expected command and result after CliStarterInternalIT.testTrace, but make the fixture self-contained so the Homebrew test does not fetch or depend on the OpenFastTrace repository. This depends on step 2.

4. Make Homebrew discover the next stable release. Add a livecheck strategy only if Homebrew cannot infer versions from the GitHub Release JAR URL. Leave out no_autobump!; Homebrew/core's default autobump service will detect later tagged releases and open formula version-and-checksum update PRs. Review those PRs and respond to failures or maintenance requests. This fulfills the selected automated-PR model without an OpenFastTrace GitHub token or a maintained fork workflow. This depends on step 2.

5. Validate the formula in the core checkout. Install the formula from source with the local formula enabled, run its formula test, and run Homebrew's online audit suite (brew lgtm --online, or its equivalent supported by the installed Brew version). Confirm the JAR checksum, JDK launch, oft executable, and functional trace work on macOS and Linux through Homebrew CI. This depends on steps 2-4.

6. Submit and maintain the core PR. Create the required single new-formula commit, push it to the contributor fork, and submit it to Homebrew/homebrew-core. Include the required AI-use disclosure and personally review every formula line and PR response before requesting Homebrew review. Address maintainer feedback within the fork and keep the PR to one formula. This depends on step 5.

7. Document the published installation route after merge. Update the OpenFastTrace README's Getting Pre-Built Packages / installation material with the final public command brew install openfasttrace; mention Java runtime provisioning only if Homebrew's final formula requires a caveat. Update the current versioned direct-JAR examples at the same time if a release is being prepared. Do not modify product/oftw.sh as part of Homebrew publication: its fixed version is a separate CI-wrapper defect, unrelated to the core formula. This depends on formula acceptance.

8. Release integration. For the product release used by the initial formula, follow the existing doc/developer_guide.md release process: update parent/pom.xml revision and release notes, run release.yml, then verify that the GitHub Release contains the JAR and checksum before creating the Homebrew PR. No changes to .github/workflows/release.yml or .github/workflows/github_release.sh are planned because they already produce the necessary immutable artifacts. This is a prerequisite for step 2 when a newer release is required.

Relevant files

• /Users/chris/git/openfasttrace/product/pom.xml — source of the shaded openfasttrace-${revision}.jar, its CLI manifest entry point, and the reason a portable-JAR formula is appropriate; no change expected.
• /Users/chris/git/openfasttrace/.github/workflows/github_release.sh — existing release asset and SHA-256 generator; no change expected.
• /Users/chris/git/openfasttrace/.github/workflows/release.yml — existing release workflow; no change expected.
• /Users/chris/git/openfasttrace/product/src/test/java/org/itsallcode/openfasttrace/cli/CliStarterInternalIT.java — reuse testTrace as the behavioral reference for the formula test.
• /Users/chris/git/openfasttrace/README.md — document Homebrew installation only after the formula is merged.
• Homebrew/homebrew-core/Formula/o/openfasttrace.rb — new external contribution; not in the current workspace.

Verification

1. Before submission, verify the release JAR and checksum downloaded from its GitHub Release agree, and run java -jar with a Java 17 runtime as a direct artifact sanity check.
2. In the Homebrew/core checkout, run HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source openfasttrace.
3. Run brew test openfasttrace and ensure the temporary Markdown trace succeeds with an asserted result.
4. Run brew lgtm --online (or the equivalent current Homebrew validation command), including the new-formula audit checks.
5. Let Homebrew/core CI demonstrate supported macOS and Linux installs. After merge, verify brew install openfasttrace on a clean machine and oft trace on a minimal document.
6. For only the later README documentation change, run ./oft-self-trace.sh and mvn -T 1C verify because this repository treats traced documentation and its build quality gates as authoritative.

Decisions

• First route: homebrew/core, selected by the user.
• Release maintenance: automated PRs, implemented through Homebrew/core autobump rather than OpenFastTrace CI.
• Artifact source: GitHub Release JAR with Homebrew-managed SHA-256 verification, not Maven Central and not an unversioned Git checkout.
• Formula scope: one oft CLI command and its Java 17 runtime; no plugins, shell completions, cask, bottle changes, or macOS-only behavior.
• Documentation/spec scope: this does not change product runtime behavior. Add the README installation command after publication, but do not manufacture OpenFastTrace req/dsn markers for formula code that lives in another repository. The current repository has no doc/changesets/ directory despite the newer planning skill mentioning one; use its established release-note process if this ships with a product release.