document risk of version mismatch, add GHA check

.github/workflows/sdk_publish.yaml

@@ -7,6 +7,15 @@ name: "04 - Publish to Maven Central and GitHub Release"
       - RELEASES.md
       - '*/RELEASES.md'
 jobs:
+  test_and_lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gradle/gradle-build-action@v2
+      - uses: uses: open-policy-agent/setup-opa@v2
+      - run: ./gradlew test lint checkstyleMain checkstyleTest
+      - run: ./scripts/check-version-mismatch.sh
+
   publish:
     name: Publish Java SDK
     runs-on: ubuntu-latest

docs/site/docs/maintenance/change-speakeasy.md

@@ -1,5 +1,9 @@
 # Regenerate Speakeasy-Manged Code
 
+!!! warning
+
+    Be aware that manually generating using `speakeasy run` can cause the version numbers in `.speakeasy/gen.yaml` and `RELEASES.md` to drift out of sync, which can result in releases being published with inconsistent version numbers. Be sure to check this before releasing from any branch where manual generation has been performed.
+
 Speakeasy-managed portions of the `opa-java` SDK are normally kept upt to date by [SDK generation workflow](https://github.com/StyraInc/opa-java/blob/main/.github/workflows/sdk_generation.yaml). Usually, no additional actions are required beyond merging the PRs this workflow creates automatically. For more information, see [*Releases*](./releases.md).
 
 If you need to re-generate the Speakeasy portions of the code manually, you can use the following shell commands:

docs/site/docs/maintenance/releases.md

@@ -4,6 +4,10 @@
 
     There are manual steps required before releases will appear on Maven Central, scroll down for more information.
 
+!!! warning
+
+    Before performing a release, be sure to check that the version number in `.speakeasy/gen.yaml` matches the one in `RELEASES.md`, otherwise the GitHub and Maven Central release may have inconsistent version numbers. You can do this by running `./scripts/check-version-mismatch.sh`
+
 Releases normally happen when the Speakeasy automation in the [SDK generation workflow](https://github.com/StyraInc/opa-java/blob/main/.github/workflows/sdk_generation.yaml) detects that a dependency needs updated, or the code generation changes. It should automatically create a PR (for example, [#40](https://github.com/StyraInc/opa-java/pull/40)) which updates the [`RELEASES.md`](https://github.com/StyraInc/opa-java/blob/main/RELEASES.md) file. This workflow runs nightly.
 
 You can force the creation of one of these PRs by running the workflow manually and checking "Force generation of SDKs" option. In this situation, the PR is created even if nothing has changed. This can be useful if you need to force a release for some reason or another.

scripts/check-version-mismatch.sh

@@ -0,0 +1,19 @@
+#!/bin/sh
+
+# This script checks that the version numbers reported in RELEASES.md and in
+# .speakeasy/gen.yaml match.
+
+set -e
+set -u
+set -x
+
+GEN_YAML_VERSION="$(opa eval -f raw -I 'input.java.version' < .speakeasy/gen.yaml)"
+
+RELEASES_MD_VERSION="$(awk '/^### Generated/ {s=1} s==1 && /java v[0-9]/ {s=0; print}' < RELEASES.md  | tail -n1 | cut -d'[' -f 2 | cut -d']' -f 1 | cut -d' ' -f2 | tr -d 'v')"
+
+if [ "$GEN_YAML_VERSION" != "$RELEASES_MD_VERSION" ] ; then
+	printf "ERROR: .speakeasy/gen.yaml (%s) and RELEASES.md (%s) disagree on the current version, creating a release in this state may result in inconsistent versions appearing in Maven and GitHub\n" "$GEN_YAML_VERSION" "$RELEASES_MD_VERSION" 1>&2
+	exit 1
+fi
+
+exit 0