Packaging, signing and release
Rules on this page 29
| ID | Level | Rule |
|---|---|---|
| Targets | ||
| REL-01 | MUST | jpackage builds the installers for the five targets in the table above, each on its own
runner, through the Maven dist profile.
|
| REL-02 | SHOULD | Downloads are named <App>-<version>-<target>.<ext>.
|
| REL-03 | MUST | JReleaser ( jreleaser.yml) only creates the GitHub release: it builds nothing, and
attaches every file and checksums_sha256.txt.
|
| REL-04 | SHOULD | The release notes are the version’s section of CHANGELOG.md.
|
| REL-05 | MUST | The Maven version is the single source of truth: a tag vX.Y.Z releases the version in
pom.xml.
|
| REL-06 | SHOULD | master carries a -SNAPSHOT version, and a post-release job opens the pull request that
bumps it to the next snapshot.
|
| REL-07 | SHOULD | A release-asset check fails the run before publishing when an expected file is missing.
|
| REL-08 | SHOULD | On Linux, a .desktop file’s StartupWMClass is the JavaFX app class.
|
| REL-09 | SHOULD | On Linux, AppStream metainfo has the id io.github.adriandeleon.<App>.
|
| REL-10 | SHOULD | Packaging trains an AOT cache (JDK 25 Leyden) to cut start-up time; Linux legs run the
training under xvfb.
|
| Install methods | ||
| REL-11 | MUST | The GitHub release offers every download on every platform: the .dmg, .msi, .deb,
.rpm, .AppImage and .tar.gz, with checksums.
|
| REL-12 | SHOULD | On macOS (Apple Silicon) the app installs with
brew install --cask adriandeleon/tap/<app>: JReleaser’s brew packager writes the cask to
adriandeleon/homebrew-tap. A cask takes exactly one artifact,
so it serves Apple Silicon, and Intel Macs use the macos-x64 DMG.
|
| REL-13 | SHOULD | On Windows x64 the app installs with winget install AdrianDeLeon.<App>: JReleaser’s
winget packager opens a pull request on microsoft/winget-pkgs
from the adriandeleon fork. The package identifier is AdrianDeLeon.<App>, the moniker the app’s lower-case
name.
|
| REL-14 | SHOULD | Both packagers read a PACKAGES_TOKEN secret, a classic personal access token with repo
scope. Without it JReleaser skips both, and the GitHub release still publishes.
|
| Signing | ||
| REL-15 | MUST | The macOS .dmg is signed with the Developer ID Application certificate (team 8JKSF797L8),
with the hardened runtime and per-app entitlements, notarized with notarytool, stapled and checked with
spctl; then the notarized app is launched once.
|
| REL-16 | MUST | Linux downloads are signed with the one shared OpenPGP release key (“Adrian De Leon (release
signing)”) in a separate sign-linux job: rpmsign for the .rpm, a debsigs origin signature for the .deb,
and an armored .asc beside every file. The public key is committed as packaging/linux/signing-key.asc and
attached to each release.
|
| REL-17 | SHOULD | The Windows .msi is signed with Authenticode, once the certificate is chosen.
|
| REL-18 | MUST | Every download has a GitHub build provenance attestation
( actions/attest-build-provenance), which gh attestation verify checks.
|
| CI/CD (GitHub Actions) | ||
| REL-19 | MUST | ci.yml runs on every push to master and every pull request: Format
(spotless:check) and Build & Test (./mvnw verify, coverage gate included) on JDK 25. Both are required
status checks for master.
|
| REL-20 | SHOULD | full-tests.yml runs the full suite on Linux, macOS and Windows daily, on a pull request
labeled full-ci, and before every release, and lists flaky tests in the job summary.
|
| REL-21 | MUST | release.yml runs on a v* tag that matches the pom version, with workflow_dispatch as a
dry run. It runs the five-target matrix, the signing jobs, attestations, the release-asset check, JReleaser, then
the bump to the next snapshot. A dry run builds and signs and publishes nothing.
|
| REL-22 | MUST | Every workflow pins each third-party action to a commit SHA, with its version in a comment
( actions/setup-java@b843ebf… # v6.1.0).
|
| REL-23 | MUST | Dependabot updates github-actions and maven weekly.
|
| REL-24 | MUST | Every workflow starts from permissions: contents: read; only a job that needs write access
asks for it, in its own block.
|
| REL-25 | SHOULD | Every workflow sets up JDK 25 with actions/setup-java and cache: maven.
|
| REL-26 | MUST | Every job has timeout-minutes, and concurrency cancels a superseded pull-request run,
never a run on master.
|
| REL-27 | MUST | CI uploads the surefire reports even when tests fail, and the JaCoCo report; it writes the
coverage totals to the job summary.
|
| REL-28 | MUST | Signing skips cleanly when the secrets are absent (forks, dry runs), so they still build; a tag
without them fails.
|
| REL-29 | MUST | The packaged app is launched once on each OS before a release (a smoke test).
|
Targets
Section titled “Targets”Each target builds on its own GitHub-hosted runner. jpackage and JavaFX natives are host-specific, so there is no cross-building.
| Target | Runner | Downloads |
|---|---|---|
| Linux x64 | ubuntu-latest | .deb, .rpm, .AppImage, .tar.gz, fat jar |
| Linux arm64 | ubuntu-24.04-arm | .tar.gz (and .deb where the app’s tooling allows), fat jar |
| macOS arm64 | macos-15 | .dmg |
| macOS x64 | macos-15-intel | .dmg (the last Intel image, good to about Aug 2027) |
| Windows x64 | windows-latest | .msi, fat jar |
| Windows arm64 | — | Not possible yet: OpenJFX publishes no win-aarch64 natives (JDK-8314064). ARM users run the x64 MSI under emulation. |
- REL-01 MUST jpackage builds the installers for the five targets in the table above, each on its own
runner, through the Maven
distprofile.- Check (code): the release workflow’s build matrix lists
linux-x64,linux-arm64,macos-arm64,macos-x64andwindows-x64on those runners, andpom.xmlhas adistprofile. - Reference: Editora
release.yml(thebuildjob),pom.xml(dist).
- Check (code): the release workflow’s build matrix lists
- REL-02 SHOULD Downloads are named
<App>-<version>-<target>.<ext>.- Check (code): the release-asset check builds the expected names this way.
- Reference: Editora
scripts/release/CheckRelease.java(expectedAssets).
- REL-03 MUST JReleaser (
jreleaser.yml) only creates the GitHub release: it builds nothing, and attaches every file andchecksums_sha256.txt.- Check (code):
jreleaser.ymlattaches the build matrix’s files and runs after the build jobs. - Reference: Editora
jreleaser.yml, thereleasejob inrelease.yml.
- Check (code):
- REL-04 SHOULD The release notes are the version’s section of
CHANGELOG.md.- Check (code): the release job hands JReleaser that section as the changelog.
- Reference: Torrenta
scripts/release/ReleaseNotes.java. Editora’s release notes are still its commit list.
- REL-05 MUST The Maven version is the single source of truth: a tag
vX.Y.Zreleases the version inpom.xml.- Check (code): the release workflow fails when the tag and the pom version differ.
- Reference: Editora’s “Check the tag against the pom version” step in
release.yml.
- REL-06 SHOULD
mastercarries a-SNAPSHOTversion, and a post-release job opens the pull request that bumps it to the next snapshot.- Check (code): the pom’s version on
masterends in-SNAPSHOT, andrelease.ymlhas the bump job. - Reference: Editora’s
bumpjob inrelease.yml.
- Check (code): the pom’s version on
- REL-07 SHOULD A release-asset check fails the run before publishing when an expected file is missing.
- Why: GitHub releases are immutable.
- Check (code): a step before JReleaser compares the gathered files with the expected list.
- Reference: Editora’s “Verify the expected release assets” step in
release.yml.
- REL-08 SHOULD On Linux, a
.desktopfile’sStartupWMClassis the JavaFX app class.- Why: the running window then belongs to the menu entry and shows its icon.
- Check (code):
packaging/linux/<App>.desktopsetsStartupWMClass=com.<app>.App. - Reference: Editora
packaging/linux/Editora.desktop, Torrentapackaging/linux/Torrenta.desktop.
- REL-09 SHOULD On Linux, AppStream metainfo has the id
io.github.adriandeleon.<App>.- Check (code):
packaging/linux/io.github.adriandeleon.<App>.metainfo.xmlcarries that<id>. - Reference: Torrenta
packaging/linux/. Editora’s metainfo id (com.editora.Editora) predates the rule.
- Check (code):
- REL-10 SHOULD Packaging trains an AOT cache (JDK 25 Leyden) to cut start-up time; Linux legs run the
training under
xvfb.- Check (code): the
distbuild runs a training launch with-XX:AOTCacheOutput, and the Linux release legs installxvfb. - Reference: Editora
scripts/aot_build.java.
- Check (code): the
Install methods
Section titled “Install methods”- REL-11 MUST The GitHub release offers every download on every platform: the
.dmg,.msi,.deb,.rpm,.AppImageand.tar.gz, with checksums.- Check (code):
jreleaser.ymlattaches each of these types. - Reference: Editora
jreleaser.yml.
- Check (code):
- REL-12 SHOULD On macOS (Apple Silicon) the app installs with
brew install --cask adriandeleon/tap/<app>: JReleaser’sbrewpackager writes the cask toadriandeleon/homebrew-tap. A cask takes exactly one artifact, so it serves Apple Silicon, and Intel Macs use themacos-x64DMG.- Why: the official homebrew-cask repository has notability rules a new project does not meet, so the family shares one personal tap.
- Check (code):
jreleaser.ymlhas abrewpackager for that tap;jreleaser package --basedir .writes the cask locally, to check it without releasing. - Reference: Torrenta and Termina
jreleaser.yml; Editora has no packager yet.
- REL-13 SHOULD On Windows x64 the app installs with
winget install AdrianDeLeon.<App>: JReleaser’swingetpackager opens a pull request onmicrosoft/winget-pkgsfrom theadriandeleonfork. The package identifier isAdrianDeLeon.<App>, the moniker the app’s lower-case name.- Check (code):
jreleaser.ymlhas awingetpackager with that identifier;jreleaser package --basedir .writes the manifests locally. - Reference: Torrenta and Termina
jreleaser.yml; Editora has no packager yet.
- Check (code):
- REL-14 SHOULD Both packagers read a
PACKAGES_TOKENsecret, a classic personal access token withreposcope. Without it JReleaser skips both, and the GitHub release still publishes.- Why: the workflow’s own token cannot write to the tap or open a pull request on the fork.
- Check (code):
release.ymlpassesPACKAGES_TOKENto JReleaser and leaves the packagers out when it is empty. - Reference: Torrenta and Termina
release.yml.
winget is reviewed by Microsoft: the first submission for a new publisher is checked by a person, not merged automatically.
Status on 2026-11-06: the tap exists and holds no casks yet. Torrenta and Termina have both packagers configured, waiting for the token. Mirada’s first winget submission (microsoft/winget-pkgs#471599) is open.
Signing
Section titled “Signing”- REL-15 MUST The macOS
.dmgis signed with the Developer ID Application certificate (team 8JKSF797L8), with the hardened runtime and per-app entitlements, notarized withnotarytool, stapled and checked withspctl; then the notarized app is launched once.- Check (code):
release.ymlimportsMACOS_CERT_P12andMACOS_CERT_PASSWORD, notarizes withAPPLE_API_KEY_P8,APPLE_API_KEY_IDandAPPLE_API_ISSUER, staples, runsspctland launches the app. - Reference: Editora’s “Import signing certificate (macOS)” and “Notarize DMG (macOS)” steps in
release.yml,packaging/macos/Editora.entitlements. Done in all six apps.
- Check (code):
- REL-16 MUST Linux downloads are signed with the one shared OpenPGP release key (“Adrian De Leon (release
signing)”) in a separate
sign-linuxjob:rpmsignfor the.rpm, a debsigs origin signature for the.deb, and an armored.ascbeside every file. The public key is committed aspackaging/linux/signing-key.ascand attached to each release.- Check (code):
release.ymlhas asign-linuxjob that readsLINUX_GPG_KEYandLINUX_GPG_PASSPHRASEand runs the shared scripts, andpackaging/linux/signing-key.ascexists. - Reference: Editora
scripts/release/sign-linux-packages.sh,scripts/release/check-linux-signatures.sh. Done in Editora, Torrenta, Termina and Modula; Mirada partly; nux not yet.
- Check (code):
- REL-17 SHOULD The Windows
.msiis signed with Authenticode, once the certificate is chosen.- Check (code): the Windows leg signs the
.msibefore it is uploaded. - Reference: no app yet. Open decision: SignPath Foundation (free for OSS), a Certum Open Source certificate, or Azure Trusted Signing. Until then MSIs are unsigned and SmartScreen warns.
- Check (code): the Windows leg signs the
- REL-18 MUST Every download has a GitHub build provenance attestation
(
actions/attest-build-provenance), whichgh attestation verifychecks.- Check (test): a test keeps the attested files and the files JReleaser attaches the same list.
- Reference: Editora’s “Attest build provenance” step in
release.yml,ReleaseSupplyChainTest. Done in Editora, Termina and Mirada.
The certificate renews before 2027-11-30; the Apple membership before 2027-10-31.
CI/CD (GitHub Actions)
Section titled “CI/CD (GitHub Actions)”- REL-19 MUST
ci.ymlruns on every push tomasterand every pull request: Format (spotless:check) and Build & Test (./mvnw verify, coverage gate included) on JDK 25. Both are required status checks formaster.- Check (code):
ci.ymltriggers onpushtomasterand onpull_request, with the two jobs; the repository’s rules formasterrequire both. - Reference: Editora
ci.yml.
- Check (code):
- REL-20 SHOULD
full-tests.ymlruns the full suite on Linux, macOS and Windows daily, on a pull request labeledfull-ci, and before every release, and lists flaky tests in the job summary.- Check (code):
full-tests.ymlhas ascheduleand apull_requesttrigger gated on the label, and the release preflight waits for its run on the tagged commit. - Reference: Editora
full-tests.yml,scripts/ci/ReportFlakes.java, and the “Check that the Full tests passed on this commit” step inrelease.yml.
- Check (code):
- REL-21 MUST
release.ymlruns on av*tag that matches the pom version, withworkflow_dispatchas a dry run. It runs the five-target matrix, the signing jobs, attestations, the release-asset check, JReleaser, then the bump to the next snapshot. A dry run builds and signs and publishes nothing.- Check (code):
release.ymltriggers on the tag pattern andworkflow_dispatch, and a dispatch runs JReleaser with--dry-run. - Reference: Editora
release.yml.
- Check (code):
- REL-22 MUST Every workflow pins each third-party action to a commit SHA, with its version in a comment
(
actions/setup-java@b843ebf… # v6.1.0).- Check (code): every
uses:in.github/workflows/ends in a 40-character SHA and a# vX.Y.Zcomment. - Reference: Editora
.github/workflows/.
- Check (code): every
- REL-23 MUST Dependabot updates
github-actionsandmavenweekly.- Check (code):
.github/dependabot.ymllists both ecosystems withinterval: weekly. - Reference: Editora
.github/dependabot.yml.
- Check (code):
- REL-24 MUST Every workflow starts from
permissions: contents: read; only a job that needs write access asks for it, in its own block.- Check (code): each workflow’s top-level
permissionsiscontents: read, and everywritesits in a job’s ownpermissions. - Reference: Editora
release.yml:release(publish),bump(the pull request) andpreflight(start a Full tests run).
- Check (code): each workflow’s top-level
- REL-25 SHOULD Every workflow sets up JDK 25 with
actions/setup-javaandcache: maven.- Check (code): each
setup-javastep hasjava-version: '25'andcache: maven. - Reference: Editora uses Temurin in
ci.ymlandfull-tests.yml, and Liberica for the release build, for linux-aarch64 coverage.
- Check (code): each
- REL-26 MUST Every job has
timeout-minutes, andconcurrencycancels a superseded pull-request run, never a run onmaster.- Check (code): every job sets
timeout-minutes;cancel-in-progressis true only forpull_requestevents. - Reference: Editora
ci.yml(cancel-in-progress: ${{ github.event_name == 'pull_request' }}).
- Check (code): every job sets
- REL-27 MUST CI uploads the surefire reports even when tests fail, and the JaCoCo report; it writes the
coverage totals to the job summary.
- Check (code): the test reports upload under
if: always(), and a step appends the totals to$GITHUB_STEP_SUMMARY. - Reference: Editora’s “Upload test reports and coverage data” and “Summarise coverage” steps in
ci.yml.
- Check (code): the test reports upload under
- REL-28 MUST Signing skips cleanly when the secrets are absent (forks, dry runs), so they still build; a tag
without them fails.
- Check (code): each signing step checks its secrets first, skips without them, and fails on a tag push.
- Reference: Editora’s “Import signing certificate (macOS)” step checks
MACOS_CERT_P12first.
- REL-29 MUST The packaged app is launched once on each OS before a release (a smoke test).
- Check (code):
release.ymlruns the packaged launcher on every target before JReleaser. - Reference: Torrenta’s “Smoke-test the packaged app” step runs the launcher in every target’s image. Editora
runs only the notarized macOS app (
--version,--check-terminal).
- Check (code):
Pauta 4.3.0 · · Changelog · This page in the latest edition