Continuous integration

Each package has one test workflow and one release workflow:

Package Test Release

arcadedb-jvm (the JVM build)

test-jvm.yml

release-jvm.yml

arcadedb (the native build)

test-native.yml

release-native.yml

The release workflows call the test workflows (workflow_call) and then publish; see Release. Two workflows test the arcadedb-jvm package: test-jvm.yml builds a wheel and runs the unit tests, and test-python-examples.yml runs the scripts in examples/. Both build the wheel once for each platform, on a native runner of that platform (Build arcadedb-jvm wheel (<platform>) and Build wheel for examples (<platform>)), and install that one file into each Python they test. test-native.yml builds and tests the arcadedb (native) package; see Native build.

The workflow docs.yml builds these docs (the Antora component in docs/) as a site of its own with docs/antora-playbook.yml, on every pull request and push to main that changes docs/, and attaches the site as the docs-site artifact. Download it from the run to read a page as it will render. The test workflows ignore docs/* and .adoc, so for a docs-only pull request this job is the only check. A warning fails it: a broken xref:, a misspelled {attribute}, an AsciiDoc syntax problem. Pages link into the main ArcadeDB manual as {arcadedb-docs-url}/<page>, not with an arcadedb:: xref, which the component on its own cannot resolve. To build the site locally, run npx -p @antora/[email protected] -p @antora/[email protected] antora docs/antora-playbook.yml from the repository root and open docs/build/site/index.html.

The package supports four platforms and four Python versions (3.11 to 3.14). That is 16 combinations. The organisation shares one runner limit with ArcadeData/arcadedb, so each macOS or Windows job delays the upstream jobs too, and not every combination runs.

One wheel for each platform

The wheel of arcadedb-jvm is tagged py3-none-<platform> (setup.py), like the native wheel: it carries a JRE for its platform, but nothing in it is compiled against CPython. So a Python version is a test, not a build. test-jvm.yml has two jobs:

  • Build arcadedb-jvm wheel (<platform>) builds the wheel once for each platform and uploads it as wheel-<platform>. scripts/verify_wheel_tag.py fails the build when the wheel is not py3-none-<platform>.

  • Test arcadedb (<platform>, Python <version>) downloads that wheel and installs it into one Python. It builds nothing. The release publishes these same four files.

The requires-python of the package is >=3.11,<3.15. The wheel tag no longer keeps pip off Python 3.15, so the cap does it. JPype has no 3.15 wheel yet; remove the cap, and add 3.15 to the matrix, when it has one.

What runs when

The script scripts/select_matrix.py chooses the combinations. The first job of each workflow, Download ArcadeDB JARs, runs it and passes the result to the next jobs: the test legs and the platforms to build (--wheels).

Event Unit tests (Test arcadedb) Examples (Test Python Examples)

Pull request

10 legs: linux/amd64 on all four Python versions. linux/arm64, darwin/arm64 and windows/amd64 on Python 3.11 and 3.14.

All four platforms on Python 3.14.

Push to main, the nightly run, a manual run, a release

The same 10 legs.

All 16 combinations.

The unit tests run the same 10 legs on every event, like the native package (all Python versions on one Linux platform, the oldest and the newest elsewhere). They were 16 legs on main, the nightly run and a release before the wheel became py3-none; the extra legs tested the same file again. A pull request runs 28 checks: 14 test jobs (10 and 4), 8 wheel builds (4 for each workflow), the two Download ArcadeDB JARs jobs, the two summary jobs, Bandit security scan and Dependency floor audit. The other events run 40: the examples run all 16 combinations there, from 4 wheel builds.

The names of the test jobs do not change: Test arcadedb (<platform>, Python <version>). A check keeps its history when a pull request runs fewer of them.

release-jvm.yml expects exactly four wheels, one for each platform, all py3-none. It checks the count, the tags, the sizes and the names before it publishes. The nightly run also tests against the newest arcadedata/arcadedb:latest image.

Other rules

  • A pull request that changes only documentation (docs/*, .adoc, CLAUDE.md, examples/README.md, LICENSE*) runs nothing.

  • A draft pull request skips the platform jobs. Marking it ready for review starts them.

  • A new push to a pull request cancels the run it replaces. A run on main is never cancelled.

Native build

The workflow test-native.yml builds the native image of the arcadedb package and runs the test suite against the installed wheel. It does not follow the table above. It never publishes; release-native.yml calls it on a version tag.

  • A pull request runs it only when native paths change: native/, src/arcadedb/, tests/**, scripts/select_native_matrix.py or test-native.yml itself. Changes under tests/ and src/arcadedb/ are included because both backends share those files, so a shared test or source can break native parity without touching a native file; docs outside those paths do not run it. It then runs on linux-x86_64 with Python 3.12 only.

  • A push to main, the nightly run, a manual run (dispatch) run all four platforms: linux-x86_64, linux-aarch64, macos-arm64 and windows-x64 (Python 3.12 and 3.14). A release (release-native.yml calls the workflow with release: true) runs the same four platforms on all four Python versions, 16 legs.

  • The pyver job installs the already built linux-x86_64 wheel (no rebuild) into the Pythons that the full parity runs of the event leave out (3.11, 3.13 and 3.14 on a pull request; 3.11 and 3.13 on a push to main, the nightly run and a dispatch; none on a release) into 3.15 and into the free-threaded 3.14t, and runs 13 test files there (14 where polars installs; 3.15 has no jpype1 wheel, so it leaves out the two files that need jpype1), about 20 seconds of tests per Python. It is informational: release-native.yml reads only the native-passed- markers and the native-wheel- wheels, so a red pyver leg never blocks a release. The 3.14t leg has no polars (no free-threaded wheel exists), so it skips test_dataframe_ingest.py. scripts/select_native_matrix.py decides its legs.

  • A native image build takes about 1 to 2.5 hours for each platform. The organisation shares one runner limit with upstream ArcadeDB, so do not add runs lightly. Change the paths or the matrix of test-native.yml only for a reason that you can write down.

Change the selection

Edit JVM_LEGS (unit tests, every event) or PULL_REQUEST_LEGS (examples on a pull request) in scripts/select_matrix.py. The test tests/test_select_matrix.py fixes the legs, so a change that shrinks them fails. When you add a Python version, add it to PYTHONS in the script and to the classifiers in pyproject.toml. A test checks that both lists are the same, that requires-python starts at the oldest of them and stops before the minor after the newest. When you drop one, remove it from the same places and update the counts in the test.