Release trains for the three Drivine libraries:
| Library | Repo | Registry |
|---|---|---|
| drivine4j | liberation-data/drivine4j | Maven Central, org.drivine:drivine4j |
| drivine | liberation-data/drivine | npm, @liberation-data/drivine |
| drivine-python | liberation-data/drivine-python | PyPI, drivine |
A train is a set of library versions that ship together, named by date: train 2026.11 is "Drivine 2026.11". A
second train in the same month is 2026.11.1.
The libraries keep their own semantic versions. They aren't aligned: a train might hold drivine4j 0.4.0, drivine 4.0.0 and drivine-python 0.3.0. What the train records is that those versions were released together, and the Cypher spec tag all three were tested against.
Each train has a manifest in trains/:
{
"train": "2026.11",
"spec": "v0.6.16",
"libraries": {
"drivine4j": "0.4.0",
"drivine": "4.0.0",
"drivine-python": "0.3.0"
},
"released": "2026-11-03"
}A draft manifest has "released": null, and "pending" lists the libraries whose release PRs were opened for it. A
library left out of a train's changes (skip) still appears, at the version on its default branch.
This repo doesn't build or publish anything. Each library releases itself: merging a version bump to its default
branch runs its release.yml, which tags v<version>, runs the full gate, and publishes (see each repo's
RELEASING.md). This repo starts those workflows and records the result.
All three workflows are under Actions in this repo, and start with Run workflow.
-
Preflight (optional; Prepare train runs it). For each library, on its default branch, it checks that the latest
ci.ymlrun is green (waiting for one still running), reads the Cypher spec tag the library tests against, and runs a release dry run (release.ymlbyworkflow_dispatch, which never publishes). The job summary has a table of all three. Different spec tags are a warning, or a failure withstrict_spec. -
Prepare train. Inputs:
train: the name,YYYY.MM. Empty means this month (UTC).drivine4j,drivine,drivine-python: eachskip,patch,minor,major,prerelease, or an exact version such as0.4.0or0.4.0-rc.1.strict_spec: passed to Preflight.
It runs Preflight, then works out each library's new version from the version on its default branch, and checks that it's above the last release and that neither tag
v<version>nor branchrelease/v<version>exists. Then it starts each library'sprepare-release.ymlwithbumpand the exactversion, so the library and the manifest agree, waits for each run, and finds the release PR it opened. Last, it opens a PR to this repo with the draft manifest,trains/<train>.json, on branchtrain/<train>. The job summary lists the PRs.A bump from a release to a
prereleasegivesX.Y.(Z+1)-rc.0, as each library's own Prepare release does; from an-rc.Nit counts up (-rc.1).Running it again for the same train reuses a library release PR that's still open, and replaces the draft manifest. A library whose release PR has already merged would be bumped again, so give it
skipon the re-run: it's then recorded at the version it released. -
Review and merge each library's release PR. Merging it releases that library: its
release.ymltagsv<version>and publishes, after the approval itsreleaseenvironment asks for.Merge the draft manifest PR here too. (Record train also reads the draft from its branch if it isn't merged.)
-
Record train, from
mainwith inputtrain, once every library has published. It checks, for each library in the manifest, that tagv<version>exists and that the registry has the version:- Maven Central:
https://repo1.maven.org/maven2/org/drivine/drivine4j/<version>/drivine4j-<version>.pom - npm:
npm view @liberation-data/drivine@<version> version - PyPI:
https://pypi.org/pypi/drivine/<version>/json, with the version in its PEP 440 form (0.4.0-rc.1is0.4.0rc1)
and that the spec tag exists on drivine-cypher-spec. If all pass, it sets
releasedin the manifest, commits it tomain, and creates the GitHub Releasetrain-<train>, "Drivine ", listing each library version with links and the spec tag. It closes the draft manifest PR if that's still open. Maven Central can take a while to show a new version; if that's the only failure, run Record train again later.Last, it links each library's own GitHub Release
v<version>back to the train, by adding a line to the end of its notes:Part of Drivine 2026.11, with drivine4j 0.4.1, drivine-python 0.3.2 and Cypher spec v0.21.0.
The line names the other libraries and the spec, and ends with the hidden marker
<!-- drivine-train -->. Running it again replaces the marked line instead of adding another, and the rest of the notes is kept as it is. A library tagged without a GitHub Release gets a warning and is skipped. This step usesRELEASE_TOKEN(see Settings), as this repo's own token can't edit releases in the library repos; if it fails, the train is still recorded, and running Record train again withbacklink_onlylinks the releases.With
backlink_onlyit checks and records nothing, and only links the libraries' releases, for a train that's already recorded as released (such as one recorded before this step existed). - Maven Central:
-
Secret
RELEASE_TOKEN. A fine-grained personal access token with resource ownerliberation-data, access to drivine4j, drivine and drivine-python, and repository permissions Actions: read and write, Contents: read and write and Pull requests: read and write. (A GitHub App's installation token expires after an hour, so a stored one won't do: Preflight alone can wait longer than that. Using an App would need a step that mints a token each run, which these workflows don't have.)What the controller itself does with it: start workflows (Actions: write), read files, tags and branches (Contents: read), list PRs (Pull requests: read), and add the train's line to each library's GitHub Release (Contents: write). The write permission on Pull requests is for using the same token as
RELEASE_PR_TOKENbelow. The token is only ever given to a step asGH_TOKEN. -
Settings → Actions → General → Workflow permissions: turn on "Allow GitHub Actions to create and approve pull requests", so Prepare train can open the draft manifest PR with this repo's
GITHUB_TOKEN. -
main: Record train pushes the recorded manifest tomainwithGITHUB_TOKEN. Ifmainis protected, let GitHub Actions bypass the rule (or leavemainunprotected).
- Optional secret
RELEASE_PR_TOKEN, the same token asRELEASE_TOKEN(it needs Contents and Pull requests write on that repo).prepare-release.ymlopens the release PR with it when it's set. A PR opened with the repo's ownGITHUB_TOKENdoesn't start the repo'spull_requestworkflows, so without it CI won't run on the release PR by itself: push an empty commit to the PR's branch, or close and reopen the PR. Startingprepare-release.ymlfrom here doesn't change which token it uses, so this applies to trains too. - The
releaseenvironment with required reviewers, as each RELEASING.md recommends. Merging a version bump publishes, so that approval is the checkpoint.
The workflows call the scripts in scripts/, which use only bash, the Python standard library, gh, git and
npm, so they can be run locally:
python3 -m unittest discover -s scripts # the version, train and run-matching logic
GH_TOKEN=... python3 scripts/preflight.py --no-dry-run --no-wait-ci
GH_TOKEN=... python3 scripts/prepare_train.py --plan-only --drivine4j minor --drivine skip --drivine-python patch
GH_TOKEN=... python3 scripts/record_train.py --train 2026.11 --check-only
GH_TOKEN=... python3 scripts/record_train.py --train 2026.11 --link-releases --dry-run # prints each new release body--no-dry-run, --plan-only, --check-only and --dry-run start nothing and write nothing to GitHub.
Apache License 2.0. See LICENSE.