Release
A release is a Git tag. Pushing the tag starts the release workflows. This repository releases two packages: arcadedb-jvm (the JVM build) with release-jvm.yml, and arcadedb (the native build) with release-native.yml. Each release workflow calls the test workflow of its build (test-jvm.yml, test-native.yml), checks the wheels and publishes them to PyPI with trusted publishing. The workflows store no token. The sections below describe release-jvm.yml; the native release is in Native release.
Version numbering
The tag is the bare version, with no v. The tag, the wheel version and the PyPI version are the same string.
| Version | Meaning |
|---|---|
|
A development pre-release of engine release |
|
The release. The wheels ship the |
|
A fix in the Python code of the released |
The rule has five parts:
-
The order for one base
A.B.CisA.B.C.dev0,.dev1, …, thenA.B.C, thenA.B.C.post1,.post2, …. -
aN,bNandrcNare never used, previews included. -
devNstarts again at 0 when the baseA.B.Cchanges. -
A number is never reused and never skipped. PyPI refuses a version it has seen, even after a delete. The next number is one above the highest published number of that base.
-
A
devNof a released base is refused, because it would sort before the release. ApostNof a base that is not released is refused.
The base is the version of the engine. The workflow compares the tag with the version of the engine jar in the wheels, and it refuses a devN tag for a release jar and a release tag for a snapshot jar.
The engine snapshot of a dev release
Upstream publishes the snapshot engine by the day: the Docker image tags latest and A.B.C-SNAPSHOT move, and so does the Sonatype snapshot repository that the native build resolves. A .devN release therefore pins one snapshot for both packages in scripts/dev_engine_pin.json: the image by index digest, the timestamped snapshot version, and the sha256 of every arcadedb-*.jar in the image.
-
scripts/dev_engine_pin.py check --tag <VERSION>proves that the image (amd64 and arm64) and the Sonatype jars hold exactly the pinned jars. Both release workflows run it before anything is built,release-native.ymlruns it again after the native build, and the JVM jobs download the image by digest and rundev_engine_pin.py verify-jarson the jars. A difference stops the release (exit 1); a source it cannot read stops it too (exit 2). -
Only
A.B.C.devNof the pinned base gets a snapshot. A final or.postNrelease refuses it, and a snapshot other than the pinned one is refused for a dev release (tests/test_dev_engine_pin.pyruns the real step code). -
Each wheel states what it embeds:
arcadedb.ENGINE_SNAPSHOT(the timestamped version) andarcadedb.ENGINE_IMAGE_DIGEST. -
To re-pin, run
uv run --no-project python -I scripts/dev_engine_pin.py capture <image-index-digest>and replace the file in a pull request, before the tag. -
The native notices comparison is skipped for a snapshot engine (
THIRD_PARTY_NOTICES.mdnames a release), so a dev wheel is not checked against it.
How the rule is enforced
scripts/check_version.py checks the rule. It reads the published versions from the Git tags of the repository and from PyPI, and it never changes anything:
uv run --no-project python -I scripts/check_version.py <VERSION> --git-remote origin --pypi arcadedb-jvm
It exits 0 when the version is the correct next one, 1 when it is not, and 2 when a source cannot be read. Exit 2 is a failure, not a pass: the check fails closed.
The first job of each release workflow runs the same command on the pushed tag. When it fails, the workflow builds and publishes nothing. Run it by hand before you push the tag. Running the whole workflow again for a version that is already on PyPI fails the check on purpose. To retry a failed upload, re-run only the publish job.
The tests of the script are in tests/test_check_version.py.
After the tag push
scripts/after_tag_verify.sh checks a finished release: arcadedb-jvm (the run of release-jvm.yml) by default, and the native arcadedb (the run of release-native.yml) with PACKAGE=native. It only reads from GitHub and PyPI:
scripts/after_tag_verify.sh <VERSION> <PREVIOUS> <release-run-id>
PACKAGE=native scripts/after_tag_verify.sh <VERSION> <PREVIOUS> <native-release-run-id>
The second argument is the previous release of that package. Use - for the first release of the package. The script checks, for the JVM package:
-
The workflow run, and the conclusion of the publish job and of its upload step.
-
The files on PyPI: one
py3-nonewheel for each platform (the same file for every Python version), each under 100 MB, none yanked. -
The sha256 of every file on PyPI against the wheels the workflow checked.
-
A download of the wheel of each of the four platforms from PyPI (picked from the PyPI JSON, fetched with
curl, sha256 compared with the one PyPI lists), and a freshuv run --withinstall on Python 3.12 and 3.14 that opens a database and runs one SQL and one openCypher query.
For the native package the steps are the same with three differences: the checked wheels are the artifact native-release-dist; windows-x64 is required for a final release and optional for a devN release (as release-native.yml publishes it); and the smoke run asserts the native backend and that ENGINE_VERSION is the engine the tag is named after, because there is no jar to check.
It prints PASS or FAIL for each step, and its exit code is the number of failures.
Native release
The two packages release from two workflows with two PyPI environments:
| Package | Workflow | GitHub environment |
|---|---|---|
|
|
|
|
|
|
The version rule above holds for both packages. One tag starts both release workflows, and each one checks the tag against its own PyPI project.
release-native.yml has four jobs:
-
Validate tagchecks that the tag is a bare version and the next one (scripts/check_version.py). -
testcallstest-native.ymlwith the full matrix: four platforms, each on Python 3.11 to 3.14. It builds the native image and the wheel on each platform and runs the test suite of this repository against the installed wheel. It also runs thepyverjob: a subset of the tests against thelinux-x86_64wheel on Python 3.15 and on the free-threaded 3.14t. -
Verify what may be publishedreads which legs passed, applies the readiness gate below and collects the wheels. -
Publish to PyPIuploads the wheels through the environmentpypi. It refuses any wheel that is not the distributionarcadedb.
arcadedb has one trusted publisher on PyPI (release-native.yml with the environment pypi) for dev, final and post releases, and one publish job in the workflow. arcadedb-jvm has one trusted publisher (release-jvm.yml with the environment pypi-jvm). PyPI matches the workflow file name, so renaming either file means changing the publisher on PyPI first. There is no separate pre-release environment; the readiness gate below is what keeps a final release back.
-
A native pre-release (
A.B.C.devN) publishes when the builds onlinux-x86_64,linux-aarch64andmacos-arm64pass. -
Every native release, pre-release or final, also needs the two
pyverlegs (Python 3.15 and 3.14t on thelinux-x86_64wheel) to pass. The other platforms are not tested on those two Pythons. -
A FINAL native release (
A.B.CorA.B.C.postN) needs two more things:-
The repository variable
ARCADEDB_NATIVE_READINESS_BAR_METistrue. A maintainer sets it after checking the readiness bar: the correctness fixes are merged; the full suite is green on every platform, Windows included, and on Python 3.11 to 3.14; the fault and concurrency probes pass; and the documented API raises noNotOnNativeYet. -
The parity run of every platform and every Python version passes with zero
NotOnNativeYetskips.
-
-
Speed parity with the JVM build is not part of the bar.
Release day
A release happens about once a month, after upstream ArcadeDB releases an engine version. Everything below takes the version as an argument; nothing is typed into a script. <VERSION> is the tag to push (the engine release A.B.C, or A.B.C.postN for a Python-only fix of a released engine), <PREVIOUS> is the previous release of the package on PyPI (- for the first one), and <NEXT_DEV> is the first dev version of the next base. The checklist with every command is the issue template .github/ISSUE_TEMPLATE/release.md (open it once per release); open it first and tick the boxes in order.
The two packages read the engine from two different channels of the same upstream release:
-
The JVM wheels take the engine jars from the Docker Hub image
arcadedata/arcadedb:<VERSION>. -
The native build resolves
arcadedb-engineandarcadedb-serverfrom Maven Central at that version and compiles them with GraalVM CEnative-image.
Both channels must carry <VERSION>. They are published by different upstream steps and can appear hours apart, so a release is ready only when the preflight passes both.
Each step is a script, CI, or the owner’s decision. The owner’s tag push is the only step that publishes anything.
| Step | What | Who |
|---|---|---|
1 |
Preflight. Checks that the upstream GitHub release exists (not draft), that Maven Central has |
script: |
2 |
The go. Zero FAILs, the readiness bar met for a final or post release (the |
owner |
3 |
Push the tag, the bare version on the tip of |
owner (the only publishing step) |
4 |
|
CI |
5 |
After-tag verification of both packages: the workflow run and its publish step, the file set and sizes on PyPI, the sha256 of every file against the wheels the workflow checked, and a fresh |
script: |
6 |
The dev-engine bump PR. |
script: |
7 |
The notices of the new engine (below), then the CI of the bump PR, then the merge on green. |
script, CI, then merge |
Commands
# 1. preflight
uv run --no-project python -I scripts/release_preflight.py <VERSION>
# 3. the tag (owner)
git fetch origin main --no-tags && git tag <VERSION> origin/main && git push origin <VERSION>
# 3a. preview the GitHub Release notes (read-only; a tag that does not exist yet is read as the tip of main)
uv run --no-project python -I scripts/release_notes.py <VERSION> --dry-run
# 5. after the workflows finished (run ids: gh run list -R ArcadeData/arcadedb-python --branch <VERSION>)
scripts/after_tag_verify.sh <VERSION> <PREVIOUS> <jvm-run-id>
PACKAGE=native scripts/after_tag_verify.sh <VERSION> <PREVIOUS> <native-run-id>
# 6. the bump
uv run --no-project python scripts/bump_engine.py --engine <VERSION> --dev-version <NEXT_DEV> --check
uv run --no-project python scripts/bump_engine.py --engine <VERSION> --dev-version <NEXT_DEV>
GitHub Release and milestone
A release does not end on PyPI: it ends with a GitHub Release, as in the upstream repository. .github/workflows/release-notes.yml runs when release-native.yml or release-jvm.yml completes (workflow_run). It looks at both workflows for the commit of the tag and does nothing until both concluded success, so the workflow that finishes first exits quietly and the second one creates the release. Both workflows only succeed after their publish job uploaded to PyPI, and the gate also asks PyPI for both versions. A tag whose native build is held back by the readiness gate therefore gets no GitHub Release until that package is published and its publish job re-run. workflow_dispatch with the tag does the same by hand for a tag that is already published. It needs no secret: GITHUB_TOKEN with contents: write (the release), issues: write (the milestone), pull-requests: read and actions: read.
-
A.B.C.devNbecomes a GitHub pre-release.A.B.CandA.B.C.postNbecome a normal release, marked as the latest. -
The notes come from
scripts/release_notes.py. The milestone is named after the baseA.B.C(26.11.1for26.11.1,26.11.1.dev2and26.11.1.post1). A pull request is listed when it is merged, has that milestone and its merge commit is in the tag, grouped by its first matching label:bug(Bug fixes),performance(Performance),enhancement(Features),documentation(Documentation), everything else under Other. Each line is the title and(#N). The notes also have the install lines, the engine version and the PyPI pages of both packages. -
A final release lists the whole milestone. A
devNlists only what is not in the previous dev tag of the same base. A pull request without the milestone is not in the notes of a final or dev release, so check the milestone before the tag. -
A
postNdoes not use a milestone, because the final release closed it. Its notes list every pull request merged between the previous tag of the same base (the final orpost(N-1)) and the tag, found from the commits of that range, whatever milestone the pull request has or none. -
After a final release (not
devN, notpostN) the milestoneA.B.Cis closed, after what is still open in it moves to the next milestone. The next milestone is the open one with the earliest due date after this one. When there is none, the workflow creates one named after the next upstream engine version (the base of the upstreammainversion, the same command as in Choosing the next dev version) and due 30 days after the closed one. When that version cannot be read, or is the same version, nothing is moved or closed and the run fails with a message: create the next milestone with a due date and re-run the workflow. Every move is logged. The milestone auto-assignment of merged pull requests, where it is set up, then picks the next milestone, because the closed one is no longer open. -
A run for a release that already exists edits its notes and flag, so a re-run is safe.
Preview the notes before the tag, and read them again after the release:
uv run --no-project python -I scripts/release_notes.py <VERSION> --dry-run
The script only reads (gh api, so it needs gh auth login or GH_TOKEN) and prints the notes. A tag that does not exist yet is read as the tip of main.
Choosing the next dev version
A dev version of a released base is refused, so after <VERSION> is out the dev line moves to the next base. The next base is the version of upstream main, which carries -SNAPSHOT:
curl -fsS https://raw.githubusercontent.com/ArcadeData/arcadedb/main/pom.xml | sed -n '/<artifactId>arcadedb-parent<\/artifactId>/,/<\/version>/ s/.*<version>\(.*\)-SNAPSHOT<\/version>.*/\1/p'
<NEXT_DEV> is that base followed by .dev0. When the command prints <VERSION> itself, upstream has not moved main on yet: wait, and do not guess a base. The JVM dev wheels need no pin: they take the jars of the image tag latest, which follows upstream.
The notices of the new engine
native/wheel/THIRD_PARTY_NOTICES.md names the engine and is generated from the build log of the native image, so build_wheel.py fails on any difference. bump_engine.py reports it as TODO and does not edit it, and its --check stays at exit 1 until the file names the new engine. To regenerate:
-
First refresh the kept copy of the engine
NOTICE:git -C <arcadedb clone> show <VERSION>:NOTICE > native/wheel/ARCADEDB_ENGINE_NOTICE. The generated notices embed it, so a stale copy costs one more CI round (the 26.11.1 bump needed two because itsNOTICEgained an entry). -
Push the bump PR. The first
Test native (arcadedb)run stops at the notices drift check on purpose, and itsnative-build-record-linux-x86_64artifact holdsTHIRD_PARTY_NOTICES.generated.md, the output ofgen_notices.pyfor the new engine (the text is the same on every platform). -
Download the artifact with
gh run download <run-id> -R ArcadeData/arcadedb-python -n native-build-record-linux-x86_64 -D <scratch-dir>, copyTHIRD_PARTY_NOTICES.generated.mdovernative/wheel/THIRD_PARTY_NOTICES.md, and commit it to the bump branch. -
When the next run still fails on
NOTICE, run thegen_notices.py … --noticecommand that the failure message prints. -
Check with
uv run --no-project python scripts/bump_engine.py --engine <VERSION> --dev-version <NEXT_DEV> --check, which must exit 0, and wait for the CI of the PR to turn green.
Some tests and skip lists wait for the engine the native image links, and say so in a comment (for example the 29_hybrid_memory_retrieval.py line of scripts/native_examples_skip.txt). After the bump merges, find them with git grep -n -i "native build links\|native image links" and remove the ones the new engine settles.
The tests of the two scripts are tests/test_release_preflight.py and tests/test_bump_engine.py.