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.B.C.dev0, A.B.C.dev1, …​

A development pre-release of engine release A.B.C, built from ONE pinned upstream snapshot (below). devN starts at 0.

A.B.C

The release. The wheels ship the A.B.C engine jar.

A.B.C.post1, A.B.C.post2, …​

A fix in the Python code of the released A.B.C. The wheels still ship the A.B.C engine jar. postN starts at 1.

The rule has five parts:

  • The order for one base A.B.C is A.B.C.dev0, .dev1, …​, then A.B.C, then A.B.C.post1, .post2, …​.

  • aN, bN and rcN are never used, previews included.

  • devN starts again at 0 when the base A.B.C changes.

  • 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 devN of a released base is refused, because it would sort before the release. A postN of 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.yml runs it again after the native build, and the JVM jobs download the image by digest and run dev_engine_pin.py verify-jars on the jars. A difference stops the release (exit 1); a source it cannot read stops it too (exit 2).

  • Only A.B.C.devN of the pinned base gets a snapshot. A final or .postN release refuses it, and a snapshot other than the pinned one is refused for a dev release (tests/test_dev_engine_pin.py runs the real step code).

  • Each wheel states what it embeds: arcadedb.ENGINE_SNAPSHOT (the timestamped version) and arcadedb.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.md names 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-none wheel 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 fresh uv run --with install 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

arcadedb-jvm

release-jvm.yml

pypi-jvm

arcadedb (native)

release-native.yml

pypi

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:

  1. Validate tag checks that the tag is a bare version and the next one (scripts/check_version.py).

  2. test calls test-native.yml with 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 the pyver job: a subset of the tests against the linux-x86_64 wheel on Python 3.15 and on the free-threaded 3.14t.

  3. Verify what may be published reads which legs passed, applies the readiness gate below and collects the wheels.

  4. Publish to PyPI uploads the wheels through the environment pypi. It refuses any wheel that is not the distribution arcadedb.

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 on linux-x86_64, linux-aarch64 and macos-arm64 pass.

  • Every native release, pre-release or final, also needs the two pyver legs (Python 3.15 and 3.14t on the linux-x86_64 wheel) to pass. The other platforms are not tested on those two Pythons.

  • A FINAL native release (A.B.C or A.B.C.postN) needs two more things:

    • The repository variable ARCADEDB_NATIVE_READINESS_BAR_MET is true. 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 no NotOnNativeYet.

    • The parity run of every platform and every Python version passes with zero NotOnNativeYet skips.

  • 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-engine and arcadedb-server from Maven Central at that version and compiles them with GraalVM CE native-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 arcadedb-engine and arcadedb-server, that Docker Hub has the image for linux/amd64 and linux/arm64, that scripts/check_version.py accepts <VERSION> for both packages against the git tags and PyPI, that the latest conclusive runs of Test native (arcadedb), Test JVM (arcadedb-jvm) and Test Python Examples on main are green on every job, that the release workflows derive <VERSION> and the engine from the tag (the real step code of the workflows runs with TAG=<VERSION>), and that the native readiness variable is set for a final release. It only reads, prints PASS, FAIL or SKIP with the evidence, fails closed on network errors, and exits with the number of FAILs.

script: scripts/release_preflight.py

2

The go. Zero FAILs, the readiness bar met for a final or post release (the SKIP on the variable means the login cannot read it, so check it), and a decision to publish.

owner

3

Push the tag, the bare version on the tip of main. One tag starts both release workflows.

owner (the only publishing step)

4

release-jvm.yml and release-native.yml validate the tag, build and test the wheels, check them, and publish with trusted publishing. A failed upload is retried by re-running only the publish job. When both have succeeded, release-notes.yml creates the GitHub Release and, for a final release, closes the milestone (GitHub Release).

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 uv run --with install on Python 3.12 and 3.14 that opens a database and runs one SQL and one openCypher query.

script: scripts/after_tag_verify.sh and PACKAGE=native scripts/after_tag_verify.sh

6

The dev-engine bump PR. scripts/bump_engine.py moves the pins that dev, PR and nightly builds link: DEV_ENGINE, DEFAULT_VERSION and the default of the manual-run input version in test-native.yml, arcadedb.version in native/pom.xml, the default in native/scripts/build-image.sh, and the default of --version in native/wheel/build_wheel.py. --check reports drift and writes nothing; it refuses a <NEXT_DEV> that check_version.py would refuse.

script: scripts/bump_engine.py

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.devN becomes a GitHub pre-release. A.B.C and A.B.C.postN become a normal release, marked as the latest.

  • The notes come from scripts/release_notes.py. The milestone is named after the base A.B.C (26.11.1 for 26.11.1, 26.11.1.dev2 and 26.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 devN lists 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 postN does 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 or post(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, not postN) the milestone A.B.C is 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 upstream main version, 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:

  1. 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 its NOTICE gained an entry).

  2. Push the bump PR. The first Test native (arcadedb) run stops at the notices drift check on purpose, and its native-build-record-linux-x86_64 artifact holds THIRD_PARTY_NOTICES.generated.md, the output of gen_notices.py for the new engine (the text is the same on every platform).

  3. Download the artifact with gh run download <run-id> -R ArcadeData/arcadedb-python -n native-build-record-linux-x86_64 -D <scratch-dir>, copy THIRD_PARTY_NOTICES.generated.md over native/wheel/THIRD_PARTY_NOTICES.md, and commit it to the bump branch.

  4. When the next run still fails on NOTICE, run the gen_notices.py …​ --notice command that the failure message prints.

  5. 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.