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. Usually, no additional actions are required beyond merging the PRs this workflow creates automatically. For more information, see Releases.

If you need to re-generate the Speakeasy portions of the code manually, you can use the following shell commands:

speakeasy run --skip-compile --force
./scripts/post-generate-hook.sh

Subsequently, you should use ./gradlew test and ./gradlew lint to ensure that the changes did not cause any regressions.

Note

If you commit changes generated using this manual procedure, it may prevent the SDK generation workflow from detecting them as changes, which may in turn prevent the release workflow from triggering automatically.

Understanding Styra-Managed build.gradle Changes

The build.gradle file generated by speakeasy run is unsuitable for use with the opa-java project out of the box; several additional tasks and plugins need to be added. It does have some Speakeasy-managed information in it that is required though, namely any updated dependencies and their versions. As a workaround a shell script is used to post-process the build.gradle which Speakeasy generates with additional Styra-managed modifications. This script has been appropriately connected to the GitHub Actions workflow for Speakeasy "chore" PRs, thus it should not normally need to be run manually.

As a matter of convention, all post-generate modifications that are carried out automatically are kicked off by invoking scripts/post-generate-hook.sh, although at time of writing this script only calls fix-build-gradle.sh.

The script scripts/fix-build-gradle.sh performs the necessary modifications to build.gradle and settings.gradle. These changes include:

  • The root project name in settings.gradle is changed from openapi to opa.
  • The group and artifact IDs in build.gradle used for release publishing are changed from com.styra.opa and openapi to com.styra and opa respectively.
  • ./gradlew fixGradleLint to prevent the Gradle linter from complaining later about any unused dependencies added.

post-generate-hook.sh, and everything it calls, is designed to be idempotent, so you may run it as many times as you wish without any adverse effects.

As a safety feature for the potentially messy process of changing the group and artifact IDs, the fix-build-gradle.sh script will also attempt to lint for suspicious strings that may indicate an incorrectly rewritten group or artifact ID. In this situation, it will print the warning WARNING: possible incorrect group/artifact ID rewrite. If this occurs, fix-build-gradle.sh needs manual intervention to update it, as the Speakeasy generation of build.gradle has presumably changed.

Historical Note on Group/Artifact IDs

It is necessary to change the group and artifact IDs because of how Speakeasy generates code. The artifact and group IDs that are used as the "root" for code generation are specified in gen.yaml (java.groupID, java.artifactID). This results in an impedance mismatch, because in opa-java, the Speakeasy-generated code resides one level further down the package hierarchy than the human-authored high level API. It is not possible to simply set the "true" group and artifact IDs in gen.yaml because then the generated code would end up in the wrong place, have the wrong package statements, the wrong imports, etc.

When the repo is used without an artifact repository, none of this is a problem so far. Gradle is perfectly happy to build the Java code anyway even though the top level package is "wrong". This breaks down when publishing to, for example, Maven Central, since that metadata is an important part of making the package available correctly.

The workaround we settled on was allowing Speakeasy to generate everything, then simply correct the group and artifact IDs in the Gradle build files, which is the only place where that setting has an impact on being able to build and publish the library.

2024-06-21 - Adopt aditionalPlugins, additionalDependencies, and build-extra.gradle

Since opa-java was first released, Speakeasy's tooling has grown support for adding additional dependencies and plugins, and also for automatically including a build-extra.gradle via apply from. In past versions, fix-build-gradle.sh also rewrote the plugins { ... } block, and inserted a build footer into build.gradle with extra rules and dependencies. Starting 2024-06-21, these Speakeasy features have been adopted, and those aspects of fix-build-gradle.sh have been removed.

Further Reading