Snapshot of the Umamo working tree as it is
Uploaded as-is from /home/litruv/dev/vtsmaker/umamo on 2026-11-03. 1347 files. Includes the uncommitted work in progress in :edit, :runtime, and :ui, and the untracked files under module/edit/src/jvmAndroidMain/. History is not carried over. The source repo is https://github.com/umamoorg/umamo.
This commit is contained in:
@@ -0,0 +1,82 @@
|
||||
# Releasing Umamo
|
||||
|
||||
Pushing a semantic version tag builds, tests, and publishes desktop artifacts for all five supported targets.
|
||||
|
||||
## What ships
|
||||
|
||||
Two files per target, ten in total, plus a `SHA256SUMS.txt`:
|
||||
|
||||
| File | For |
|
||||
| ------------------------------------------ | ---------------------------------------------------------------------------------------- |
|
||||
| `umamo-<target>-<version>.zip` / `.tar.gz` | Self-contained app image (`:desktop:createDistributable`). Bundles a jlinked JRE. |
|
||||
| `umamo-<target>-<version>.jar` | Uber jar (`:desktop:packageUberJarForCurrentOS`). Needs a JDK/JRE 21 on the machine. |
|
||||
|
||||
Targets and the runner each is built on:
|
||||
|
||||
| Target | Runner |
|
||||
| ------------- | ------------------ |
|
||||
| `linux-x64` | `ubuntu-latest` |
|
||||
| `linux-arm64` | `ubuntu-24.04-arm` |
|
||||
| `windows-x64` | `windows-latest` |
|
||||
| `macos-arm64` | `macos-latest` |
|
||||
| `macos-x64` | `macos-15-intel` |
|
||||
|
||||
Every leg builds on its own OS and architecture. Unlike the uber jar, an application image cannot be cross-produced: jpackage jlinks the *host* JDK into the image, so cross-resolving natives would bundle one platform's Skiko/LWJGL inside another platform's runtime. The package job passes `-Pumamo.requireTargetIsHost=true` so an unexpected runner `os.arch` fails the build rather than shipping an artifact that runs nowhere.
|
||||
|
||||
Out of scope until alpha: code signing, notarization, native installers, auto-update, and any Android artifact. See `TODO.md` § Build and Distribute.
|
||||
|
||||
## File associations
|
||||
|
||||
The `.uma` document type (`application/vnd.umamo.uma+zip`, `docs/format/UMA.md` § 2) is declared once per OS in `app/desktop/build.gradle.kts` (`fileAssociation`) and in the Android manifest. What that does depends on the artifact, because on Windows and Linux jpackage applies `--file-associations` to **installers only**:
|
||||
|
||||
| Platform | Today's artifacts | With an installer |
|
||||
| -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
|
||||
| Linux | Not registered. The app image ships `lib/app/resources/umamo-uma.xml` and `umamo.desktop`; the README gives the two per-user `xdg-*` commands. | deb / rpm register the type. |
|
||||
| Windows | Not registered. *Open with* only. | msi / exe register the type. |
|
||||
| macOS | The app image's own `Info.plist` carries `CFBundleDocumentTypes`, so an unpacked `umamo.app` is the handler with no installer - but see below. | Same. |
|
||||
| Android | The manifest's VIEW intent filters; no artifact ships yet. | n/a |
|
||||
|
||||
The macOS legs publish the uber jar only until JDK 27 (the `appImage: false` note in `release.yml`), and a jar has no bundle to associate. Setting `appImage` back to `true` is therefore also what switches the macOS association on; the open-file handler in `Main.kt` is already in place for it and has not been exercised on a real bundle.
|
||||
|
||||
`OsAssociationFilesTest` (`:desktop`) holds the build script, the manifest, and both freedesktop files to the codec's `Uma.MIME_TYPE`, and evaluates the freedesktop magic against a file the writer really produces. Those files are declared as inputs of `:desktop`'s test task - they are not on its classpath, so without that an edit to one leaves the test up to date and unrun.
|
||||
|
||||
## Cutting a release
|
||||
|
||||
1. Bump `VERSION` in `module/ui/src/commonMain/kotlin/org/umamo/ui/help/ProjectInfo.kt`. The workflow **verifies** the tag against it and never injects a version so a mismatch will fail with an annotation telling you what to fix.
|
||||
2. Update the `CHANGELOG.md` with new changes under a `## [X.Y.Z] - YYYY-MM-DD` heading.
|
||||
3. Run the pre-flight checks below.
|
||||
4. Merge to `master`, then tag and push:
|
||||
```bash
|
||||
git tag vX.Y.Z && git push origin vX.Y.Z
|
||||
```
|
||||
5. The workflow creates the release as a **draft**, marked prerelease when the version carries a suffix. Download the artifacts and launch at least one per OS before publishing. The CI does not test the packaged binaries.
|
||||
6. Publish: `gh release edit vX.Y.Z --draft=false`, or discard and re-tag:
|
||||
```bash
|
||||
gh release delete vX.Y.Z --yes
|
||||
git push --delete origin vX.Y.Z && git tag -d vX.Y.Z
|
||||
```
|
||||
|
||||
Prerelease tags are supported as well, so having `-dev` or `-rc` is fine. However, jpackage rejects prerelease suffixes, so `project-version.gradle.kts` strips it for `packageVersion` while everything user visible keeps the full string.
|
||||
|
||||
To rehearse the whole pipeline without a tag, run the workflow manually(`gh workflow run release.yml --ref <branch>`). With no tag, the version gate synthesizes `v<ProjectInfo.VERSION>`, sets `publish=false`, and the publish job is skipped. All of the artifacts will be visible on the action runner page and not published as a release.
|
||||
|
||||
## Local Pre-flight Checks
|
||||
|
||||
```bash
|
||||
# Export a compatible Java SDK location other Compose's checkRuntime will error.
|
||||
export JAVA_HOME=/usr/lib/jvm/java-21-openjdk-amd64
|
||||
|
||||
./gradlew :desktop:suggestRuntimeModules # after any dependency change
|
||||
./gradlew :desktop:createDistributable :desktop:packageUberJarForCurrentOS
|
||||
./gradlew build # what the release gate runs
|
||||
|
||||
# The corpus suites specifically — see the caching caveat below.
|
||||
./gradlew :format:jvmTest :runtime:jvmTest :render:jvmTest :ui:jvmTest --rerun
|
||||
```
|
||||
|
||||
Then check the app image at `app/desktop/build/compose/binaries/main/app/`:
|
||||
|
||||
* `umamo/lib/app/umamo.cfg` — the `[JavaOptions]` block must carry `-Xmx4g` and **must not** carry `-Dumamo.testCmo3`. Compose forwards `application.jvmArgs` to jpackage as `--java-options`, so anything added there ships; the corpus-preview override is deliberately set on the `run` task alone (see the comment at the bottom of `app/desktop/build.gradle.kts`).
|
||||
* `umamo/lib/runtime/release` — the `MODULES=` line must list `java.instrument`, `java.sql`, `java.xml`, `jdk.security.auth`, and `jdk.unsupported`. The release workflow asserts this too.
|
||||
|
||||
`suggestRuntimeModules` under-reports: it misses reflective and service-loaded edges, and does not name `java.xml` even though JDOM — and therefore all of CMO3 read/write — needs it. Treat its output as a lower bound and confirm with `jdeps --list-deps` when adding a dependency.
|
||||
Reference in New Issue
Block a user