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. release-notes.yml runs after both of them have succeeded for a tag and creates the GitHub Release (and closes the milestone of a final 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 runs the tests on one Python in a throwaway uv run --no-project --with "<wheel>[test]" python -m pytest environment. 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 an installer 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

The same 10 legs.

All 16 combinations.

A manual run (dispatch), a release

All 16 combinations.

All 16 combinations.

The unit tests run 10 legs on a pull request, a push to main and the nightly run (all Python versions on one Linux platform, the oldest and the newest elsewhere), and all 16 combinations on a release and a manual run, like the native package: what is published is tested on every platform and Python it claims. release-jvm.yml calls the workflow with release: true, which the matrix step turns into the event release, because in a called workflow github.event_name is the caller’s tag push. 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. A push and the nightly run run 40: the examples run all 16 combinations there, from 4 wheel builds. A manual run and a release run 46, with the 6 extra unit-test legs.

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.

Which engine each workflow tests

The two packages get their engine from different places, so between releases they are tested against different engines:

  • test-jvm.yml and test-python-examples.yml take the engine jars from the arcadedata/arcadedb image tag, latest by default. latest is upstream’s newest snapshot and moves nightly, which is why both workflows also run every night.

  • test-native.yml links DEV_ENGINE, the newest release on Maven Central, unless the tag is a final or post version (then it links the release the tag is named after) or the engine input of a manual run says otherwise.

A JVM wheel that must carry the same engine as a release, such as the wheel of an A/B or of a release gate, comes from a manual run of test-jvm.yml with the release’s engine tag: gh workflow run "Test JVM (arcadedb-jvm)" -R ArcadeData/arcadedb-python --ref <branch> -f arcadedb-tag=26.11.1 (the engine of 26.11.1 and its .postN releases). Without the input the jars come from latest, the wheel carries another engine than the release, and a comparison with the release measures the engine as well as the change. The native build needs no such input, because it links a release engine by default.

A manual run of test-native.yml with a devN version may set engine to A.B.C-SNAPSHOT: native/pom.xml then resolves the engine jars from the Sonatype snapshot repository (snapshots on, releases off, so a release version still comes from Maven Central alone). The notices comparison of build_wheel.py is skipped for such a run, because THIRD_PARTY_NOTICES.md names a release and its jars. The plan job refuses a SNAPSHOT engine for a final or post version. A release run links a snapshot only for a .devN tag, and only the one pinned in scripts/dev_engine_pin.json (see Release); every other snapshot is refused, so a final or post release never depends on one. The legs input of a manual run chooses all four platforms (full, the default) or the one platform and one Python of a pull request (pull-request).

The dev-engine bump after each release, described in Release, moves DEV_ENGINE to the new release and closes the gap until upstream publishes the next one.

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.

  • A JVM crash in an example leaves a HotSpot hs_err_pid<pid>.log. test-python-examples.yml uploads these files as the artifacts jvm-crash-logdir-<platform>-py<version> and jvm-crash-cwd-<platform>-py<version> (issue 352); read them before you re-run a red example leg.

Repository automation

These workflows follow ArcadeData/arcadedb and need no secret. Issues and pull requests carry labels and a release milestone (one open milestone per version, with a due date).

Workflow What it does

classify-issue.yml

Labels a new issue from rules: the package from the bug form (native, jvm) and topic words (vector, performance, concurrency, timeseries). It only adds labels that exist. Run it by hand with the issue number to see the labels without applying them.

label-issue-in-progress.yml

Adds in progress to the issues a pull request closes (Closes #N in the body).

assign-milestone.yml

On merge, puts the pull request and the issues it closes into the open milestone with the earliest due date, unless they have one. Dependabot pull requests are skipped.

dependabot-auto-merge.yml

Every hour, squash-merges Dependabot pull requests that are patch or minor updates, mergeable, and have a non-empty list of checks that all succeeded. Majors and grouped updates stay open. Logic in .github/scripts/dependabot_merge.py.

dependency-review.yml

Fails a pull request that adds a dependency with a known vulnerability (moderate or worse) or a GPL, AGPL or SSPL licence. Policy in .github/dependency-review-config.yml.

gitignore-hygiene.yml

Fails when a .gitignore pattern matches a tracked file.

assign-maintainer.yml

Assigns every new issue and pull request to the maintainer when it is opened. Nothing from a pull request head is checked out or run.

To close a release, close its milestone and open the next one with its due date: assign-milestone.yml picks the open milestone that is due first.

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/**, examples/** (not examples/README.md), pyproject.toml, setup.py, scripts/select_native_matrix.py, scripts/smoke_wheel.py, scripts/run_examples.sh, scripts/native_examples_skip.txt 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 (only when a native path changed, same filter as a pull request), the nightly run (skipped when nothing changed in the last 25 hours, except on Mondays) and 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. A release needs it: a pyver leg that passes uploads the marker native-passed-pyver-py<version> (it holds the file name of the wheel the leg installed), and Verify what may be published in release-native.yml requires the markers of 3.15 and 3.14t, the two legs of a release, and that both tested the linux-x86_64 wheel that is published. A red leg stops a release before anything reaches PyPI. Only linux-x86_64 is checked on these two Pythons: the other platforms are not tested on 3.15 and 3.14t, and the JVM package has no such job. 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, and tests/test_select_native_matrix.py and tests/test_release_native_verify.py pin the gate.

  • Every test file runs in its own process (native/wheel/parity_wheel.py). A process that dies without writing its result is a CRASH row in parity-wheel.tsv with its exit code, for example CRASH(rc=0xC0000005,3221225477), and it fails the leg. On the Windows legs only (the crashes of issue 295 happen there), the harness runs such a file once more in a fresh process (--retry-crash). A retry that produces a result is a FLAKY-CRASH row: the gate lets the leg pass, the job summary lists the file with the first exit code, and on a release or a dispatch the crash-report job adds one comment to issue 295 (run URL, Python, wheel version, exit codes). A second crash, a failing test, a timeout and every crash on Linux or macOS stay failures. A process that wrote its result and then died in shutdown is a DIRTY-EXIT record (exit code, file, attempt) in the metadata, the job summary and the issue comment: it is not retried and does not fail the leg. Each Windows test process also writes a faulthandler trace, parity-wheel-xml/<file>.attemptN.fault.txt, into the parity artifact of the leg. Only a retry hides a crash, so treat a FLAKY-CRASH as an open bug: read the trace in the artifact before a release is announced.

  • The examples job runs every script of examples/ against the installed wheel of each platform (Python 3.12 and 3.14; a pull request: linux-x86_64, Python 3.12) through scripts/run_examples.sh, the runner that test-python-examples.yml uses too. scripts/native_examples_skip.txt lists, with a reason, the examples that need the JVM package. Examples summary is the one check for all its legs. These legs do not decide what a release publishes.

  • A native image build takes about 5 to 30 minutes for each platform (macOS is the slowest). 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 on the events in JVM_REDUCED_EVENTS: a pull request, a push and the nightly run; every other event runs the full matrix) 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.