Skip to content

DEV-1115 One-click Java API release workflow, with the MATLAB jar - #324

Merged
MAzalya merged 11 commits into
masterfrom
DEV-1115_release_workflow
Oct 19, 2026
Merged

MAzalya merged 11 commits into
masterfrom
DEV-1115_release_workflow

Conversation

@JongChern

@JongChern JongChern commented Oct 15, 2026 •

Copy link
Copy Markdown
Contributor

What

A one-click release for the Java API: Actions → Release Java API → Run workflow on master. It publishes to GitHub Packages, creates the GitHub Release, and updates the MATLAB jar. No uprev PR is needed.

How a release goes

  1. Run the workflow. Leave version blank for the next patch after the last API_v release (0.11.8_beta → 0.11.9_beta), or type one such as 0.12.0_beta.
  2. Merge the MATLAB PR it opens.
  3. Run ShimmerAndroidAPI's Release workflow (DEV-1115 One-click Android API release workflow ShimmerAndroidAPI#123). It builds against the newest Java release by default.
Job Runs on Permissions What it does
build PRs, dry runs, releases read-only Picks the version and refuses one that is already tagged. Tests and builds exactly as gradle.yml does.
publish real releases only packages: write (the only job with it) Publishes all three artifacts in one gradlew publish -PreleaseVersion=…, then keeps the jars it published for the release.
matlab-jar PRs, dry runs, releases read-only Builds ShimmerJavaClass.jar with shadowJar -PmatlabJava8 on its own runner, then checks that every class in it, dependencies included, is Java 8 bytecode.
release real releases only contents: write Tags API_v<version> and creates the GitHub Release with the jars and generated notes. It is not marked Latest, so Latest stays on Consensys.
update-matlab real releases only its own token Opens a PR in Shimmer-MATLAB-ID that replaces libs/ShimmerJavaClass.jar.

Publishing all three artifacts together fixes how shimmerbluetoothmanager 0.11.8_beta came to be missing: they were published by hand one at a time (DEV-1115).

The version is no longer stored in the source. The three publishing blocks read -PreleaseVersion. They fall back to local, and refuse to publish local to a remote repository. Nothing has to be committed to the protected master, and the API_v tags record what was released. Nothing else reads the version: every past uprev PR changed only these three lines.

dry_run runs build and matlab-jar without publishing, from any branch. This workflow also dry-runs on any PR that changes it, including this one.

Also in this PR

  • shimmerdriverpc publish fixed (DEV-1115 Fix shimmerdriverpc publish; refuse a 'local' publish #327, @MAzalya): the Shadow plugin's variant clashed with the plain jar, so publish failed for shimmerdriverpc after publishing the other two. The shadow variant is now left out of the publication. The thin jar goes out with its dependencies in the POM, as 0.11.7_beta did; the fat jar goes to MATLAB and the GitHub Release.
  • -PmatlabJava8 on ShimmerDriverPC compiles all three projects with --release 8. It replaces the Confluence step of hand-editing three build files to 1.8. Unlike sourceCompatibility = '1.8', it also rejects any API newer than Java 8.
  • Driver fix (separate commit): GrpcBLERadioByteTools called Process.onExit(), which is Java 9+. The jar in Shimmer-MATLAB-ID today contains that call, so starting the BLE gRPC server from MATLAB on Java 8 would throw NoSuchMethodError. It now waits on the process in a daemon thread and logs the same message.
  • Token hardening: checkouts don't leave the token in .git/config, and only the publish job can write packages. actions/* steps are pinned to commit SHAs, each the commit its v4 tag points at today.
  • Job timeouts (DEV-1115 Fix shimmerdriverpc publish; refuse a 'local' publish #327): 30 minutes on the Gradle jobs, 10 on the others.
  • Publishing URLs move from ShimmerEngineering, now a user account, to ShimmerResearch in the five build files that had them.
  • AGENTS.md documents the release steps.

Before the first real release

  • Add the repo secret MATLAB_REPO_TOKEN: a fine-grained token with resource owner ShimmerResearch, repository access limited to Shimmer-MATLAB-ID, and Contents and Pull requests read/write. Without it only the update-matlab job fails, and that job can be re-run on its own.
  • The Confluence page "Creating ShimmerJavaClass.jar" should point here.

Testing

  • Publish, to a local file repository (JDK 11):
    • Before DEV-1115 Fix shimmerdriverpc publish; refuse a 'local' publish #327, shimmerdriverpc failed while the other two published.
    • With it, all three publish. shimmerdriverpc is the 140 KB thin jar, and the POMs and Gradle module metadata give their dependencies on each other the release version, with no unspecified anywhere.
    • Without -PreleaseVersion, all three refuse and nothing is written.
  • MATLAB jar: a fresh -PmatlabJava8 build passes the full-class check (32,510 classes, all Java 8 or older). A jar missing the main class, or carrying a Java 11 dependency class, fails, and the offending class is named.
  • Version step: run against the real tags, it picks 0.11.9_beta after API_v0.11.8_beta. It refuses 0.11.8_beta (already tagged) and malformed input.
  • On GitHub: this PR's dry run (build, matlab-jar) is green. The publish, release and update-matlab jobs only run on a real release, so they are untested until the first one.

🤖 Generated with Claude Code

JongChern and others added 3 commits October 15, 2026 12:11
Process.onExit() is Java 9+. ShimmerJavaClass.jar is built as Java 8
bytecode for MATLAB, and source/target 1.8 compiled this call without
complaint, so starting the BLE gRPC server from MATLAB on Java 8 would
throw NoSuchMethodError. The jar currently in Shimmer-MATLAB-ID/libs
(built 2025-11-24) contains the call.

Wait on the process in a daemon thread instead, which logs the same
exit message. Found by building the jar with --release 8.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Actions -> "Release Java API" releases the version already in the
build files (bumped by the usual uprev PR; master is protected):
- tests and builds as gradle.yml does
- publishes shimmerdriver, shimmerbluetoothmanager and shimmerdriverpc
  in one gradlew publish, so they cannot drift apart again
- tags API_v<version> and creates the GitHub Release with the jars,
  not marked Latest
- builds ShimmerJavaClass.jar as Java 8 bytecode on its own runner and
  opens a PR replacing Shimmer-MATLAB-ID/libs/ShimmerJavaClass.jar
  (needs the MATLAB_REPO_TOKEN secret)

ShimmerDriverPC gains -PmatlabJava8, which compiles all three projects
with --release 8 in place of hand-editing three build files to 1.8.

Publishing URLs move from ShimmerEngineering, now a user account, to
ShimmerResearch. AGENTS.md documents the release steps.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The version in the build files is normally one that has already been
released until the next uprev, so stopping there made every PR dry run
end before the build it is meant to test. Dry runs now warn; a real
release still refuses.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
JongChern and others added 3 commits October 15, 2026 17:09
The version no longer lives in the source. The three publishing blocks
read -PreleaseVersion (falling back to 'local'), and Release Java API
passes it: the version typed in the Run form, or by default the next
patch after the last API_v release (0.11.8_beta -> 0.11.9_beta). The
API_v tags record what was released, so a release needs no uprev PR
and nothing has to be committed to the protected master.

Checked locally: with -PreleaseVersion=0.11.9_beta all three POMs and
their dependencies on each other are 0.11.9_beta; without it, 'local'.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
publish failed on shimmerdriverpc with "multiple artifacts with the
identical extension and classifier ('jar', 'null')": the Shadow plugin
adds ShimmerJavaClass.jar (empty classifier) to components.java, and
Gradle 8.14 (DEV-1013) rejects the clash. The PR dry run skips publish,
so the first real release would have failed there after publishing the
other two. Skip the shadow variant, which publishes the plain jar with
its dependencies in the POM, as 0.11.7_beta was.

Without -PreleaseVersion the version is 'local', and a hand-run
`gradlew publish` would push that to GitHub Packages, where it can
never be overwritten. Publishing to a remote repository now refuses
'local'; publishToMavenLocal is unaffected.

Add job timeouts so a hung Gradle daemon cannot hold a runner for the
default 6 hours.

Checked locally (JDK 11): publishToMavenLocal -PreleaseVersion=0.0.0_test
now succeeds, all three POMs and their cross-dependencies read
0.0.0_test, and shimmerdriverpc is the 140 KB thin jar. Publishing to a
file repository without -PreleaseVersion fails for all three.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
DEV-1115 Fix shimmerdriverpc publish; refuse a 'local' publish
Copilot AI lite review requested due to automatic review settings October 18, 2026 05:18

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Critical credential-exposure and dependency-version issues, plus workflow release-validation gaps, remain unresolved.

4 open issues
What changed in this PR

Adds one-click Java API release automation, MATLAB JAR updates, Java 8 support, and package URL/versioning changes.

Changes:

  • Adds release, validation, publishing, and MATLAB PR workflows.
  • Adds Java 8-compatible compilation and process monitoring.
  • Updates publishing configuration and release documentation.
File Description
ShimmerPCBasicExamples/​build.gradle Updated package URL
ShimmerLSL/​build.gradle Updated package URL
ShimmerDriverPC/​build.gradle Java 8 build and publication configuration
ShimmerDriver/​src/​main/​java/​com/​shimmerresearch/​grpc/​GrpcBLERadioByteTools.java Java 8-compatible process monitoring
ShimmerDriver/​build.gradle Versioning and repository configuration
ShimmerBluetoothManager/​build.gradle Versioning and repository configuration
AGENTS.md Release process documentation
.github/​workflows/​release.yml Release, validation, and MATLAB automation

Review effort: Lite

Comment thread .github/workflows/release.yml Resolved
Comment thread ShimmerBluetoothManager/build.gradle Resolved
Comment thread ShimmerDriver/build.gradle Resolved
Comment thread ShimmerDriverPC/build.gradle Resolved
actions/checkout persists github.token in .git/config by default, so the
Gradle build in the build job, and any plugin or dependency it runs,
could read a token with packages:write. Neither build nor matlab-jar
needs git credentials after checkout, so turn persistence off there.
update-matlab keeps it, because its git push uses it.

Raised in review on #324.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 18, 2026 05:26

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The workflow exposes a write-capable package token to PR-controlled code, creating a critical publishing risk.

1 open issue
4 resolved since last review

Review effort: Lite

Comment thread .github/workflows/release.yml Resolved
The build job ran on PRs with packages:write. Any code in a job can
recover that job's token from the runner, so a PR dry run should not
hold a write token at all. The build job is now read-only, and a new
publish job, which runs only on a real release, is the one place with
packages:write. It publishes and uploads the jars it published, so the
GitHub Release carries the same files as GitHub Packages. The release
job now waits for it.

Raised in review on #324.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 18, 2026 05:31

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The release workflow has unresolved jar compatibility and version validation gaps that could break releases.

1 open issue
1 resolved since last review

Review effort: Lite

Comment thread .github/workflows/release.yml Resolved
The check sampled three of our own classes, but ShimmerJavaClass.jar
also shades every dependency, and one built for a later Java would
break MATLAB on Java 8 just the same. Check every class instead (about
32,500, read once with Python in ~2 s), skipping module-info and
META-INF/versions entries, which Java 8 never loads, and still require
the main class to be present.

Tested on a fresh -PmatlabJava8 build (32,510 classes, all Java 8 or
older, passes), and on jars missing the main class or carrying a Java
11 dependency class (both fail, naming the class).

Raised in review on #324.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 18, 2026 05:38

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The release workflow has artifact path and version parsing issues that can prevent successful releases.

1 open issue
1 resolved since last review

Review effort: Lite

Comment thread .github/workflows/release.yml Resolved
@JongChern
JongChern requested a review from MAzalya October 18, 2026 06:19
@JongChern

Copy link
Copy Markdown
Contributor Author

@MAzalya thanks for #327, it's merged. Since then:

  • The build job's checkout no longer leaves the token in .git/config.
  • Publishing moved to a publish job that runs only on a real release. The build job, which also runs on PRs, is read-only.
  • The MATLAB jar check now covers every class, dependencies included (32,510 on a fresh build).

All Copilot threads are resolved and the dry run is green. Could you take another look?

Matches ShimmerAndroidAPI#124, which pinned checkout and setup-java in
review. Each pin is the commit its v4 tag points at today (checkout
v4.4.0, setup-java v4.9.1, upload-artifact v4.6.2, download-artifact
v4.3.0), so nothing that runs changes; setup-gradle was already pinned.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Copilot AI lite review requested due to automatic review settings October 18, 2026 06:40

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Release publishing and cross-repository automation require final human review.

No open issues 🎉

1 resolved since last review

Review effort: Lite

@MAzalya MAzalya left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approved. I re-reviewed the changes since #327:

  • The publish job is the only job with packages:write.
  • Credentials aren't persisted.
  • The pinned SHAs match their tags.
  • The matlab-jar check passed: 32,510 classes, all Java 8 or older. (The #327 description said 39,510; I added it up wrong.)

MATLAB_REPO_TOKEN is already set, so the first real release exercises publish, release and update-matlab.

Non-blocking nits, on ShimmerAndroidAPI#123 and #124 rather than here:

  1. #123's build job, which runs on PRs, still falls back to secrets.PACKAGES_READ_TOKEN, unlike #124's GITHUB_TOKEN-only approach. That secret isn't set, so nothing is exposed today.
  2. #124's checkout keeps credentials persisted. Its token is read-only, so this is low risk.

@MAzalya
MAzalya merged commit 667c93c into master Oct 19, 2026
8 checks passed
@MAzalya
MAzalya deleted the DEV-1115_release_workflow branch October 19, 2026 02:22
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants