| name | ror-release |
| description | ReadonlyREST versioning, branching, and release mechanics — pluginVersion vs publishedPluginVersion, S3 artifact pipeline, supporting a new ES version, unstable customer builds. Use when bumping versions, adding ES version support, releasing, or producing a build for a customer. |
ROR Versioning & Release
Source: beshu-tech/readonlyrest-internal (versioning.md, releasing.md), reconciled with the current repo where the docs are stale.
Versioning rules (binding)
- Stable versions are semver
X.Y.Z; unstable are X.Y.Z-preN. Both live in /gradle.properties → pluginVersion.
- ES and Kibana plugins are released in lockstep: customers must install the same ROR version on both sides. Never release one without the other.
master holds stable versions only — a -pre version on master breaks CI. develop takes -pre versions; PRs are squash-and-merged into it.
pluginVersion vs publishedPluginVersion (the iron rule)
gradle.properties has two keys:
pluginVersion — what CI builds when the value changes in a commit.publishedPluginVersion — what readonlyrest.com/download advertises (read directly from git).
Order: bump pluginVersion → wait until CI has uploaded ALL deliverables to S3 → only then set publishedPluginVersion to match. Flipping publishedPluginVersion early advertises downloads that don't exist yet.
CI artifact pipeline
- Committing a
pluginVersion change triggers the Azure pipeline's artifact stage: one zip per supported ES version, uploaded to S3 readonlyrest-data/build/<plugin_version>/.
- Each uploaded deliverable gets a git tag
v<plugin_version>_es<es_version> (e.g. v1.37.0_es7.16.2). CI skips builds whose tag already exists — so to resume a half-failed release, just re-run the pipeline; it is idempotent.
- Release closeout: update the changelog in
beshu-tech/readonlyrest-docs (changelog.md) and send the Mailchimp campaign.
Supporting a new ES version (current mechanism)
Verified against recent PRs (e.g. #1257). Files touched:
es{NN}x/gradle.properties — add the version to supportedEsVersions in the matching module. This is the single source of truth: CI build/test, the default ES module, and the docs action-string sync all derive from it (EsModuleFinder / printAllSupportedEsVersions). There is no separate version list to update.- Mirror the ES jars into the libs store, for versions Maven Central doesn't carry yet: run the Mirror ES Libs workflow (
.github/workflows/mirror-es-libs.yml) with es_versions set to the new versions (e.g. 9.5.1 9.4.5). Manual, once per version, and before the branch adding that version goes through CI — the build resolves ES dependencies from the store, so it cannot compile against jars that aren't there yet. Not what gates CI build/test (that's supportedEsVersions, step 1). (Until 2026-08: uncomment a line in ci/upload-es-artifacts.sh, push a newes/* branch to fire ci.yml's es_s3_up job, re-comment before merge. Both that job and the newes/* trigger are gone.)
- Sometimes
ror-tools/build.gradle.
Test locally first: ./gradlew integration-tests:test '-PesModule=es{NN}x'.
- Adapt code keeping old-version compatibility at all costs. Only when the new ES introduces true breaking changes: copy the latest module (
cp -r es93x es94x), add it to settings.gradle and the files above.
- The PR must come from the main repo, not a fork (artifact upload needs S3 credentials).
- For unreleased/snapshot ES versions: build ES from source (
elastic/elasticsearch repo) and publish deps to mavenLocal with ./gradlew clean publishElasticPublicationToMavenLocal (needed jars: elasticsearch SDK, transport-netty4, elasticsearch-plugin-classloader).
Unstable builds for customer support
To let a customer verify a fix mid-sprint: merge the fix PR to develop and bump the -preN number — CI uploads fresh builds to S3. Share a signed temporary link from https://download.readonlyrest.com/.
Edition caution: give the customer the edition they're licensed for — never hand an Enterprise build to a Free/PRO customer. If in doubt, ask Simone or Ben.
