Versioning & Upgrades

Taking a newer BigLedger release is a change to a version number in your build file. This page explains what the numbers mean and how to move between them without surprises.

One version for the whole platform

akaun-api, javasdk and client-sdk are always released together and always carry the same version. “We are on BigLedger 1.0.0” is a single, checkable fact about your deployment.

Always keep them aligned. Mixing versions — for example akaun-api:1.2.0 with javasdk:1.0.0 — is not tested and not supported.

What the numbers mean

Releases are numbered MAJOR.MINOR.PATCH and follow semantic versioning:

Change	Example	What it means for you
Patch	`1.0.0` → `1.0.1`	Bug fixes only. Your code compiles and behaves the same. Safe to take promptly.
Minor	`1.0.0` → `1.1.0`	New capability, added without breaking anything. Your code still compiles.
Major	`1.0.0` → `2.0.0`	Something you may compile against has changed or been removed. Expect to make changes.

A published version is never modified or replaced. Once 1.0.0 exists, its contents are fixed forever — a build that resolved it today resolves exactly the same bytes next year.

Pin an exact version

Always depend on an exact version:

implementation("com.bigledger:akaun-api:1.0.0")
implementation("com.bigledger:javasdk:1.0.0")

Do not use dynamic versions such as 1.+ or latest.release. They make your build non-reproducible and can pull in a major upgrade without warning.

How to upgrade

Read the release notes for every version between yours and the target, not just the newest one.
Change the version in your build file — both artifacts, to the same number.
Build. Compilation errors point at anything that moved; on a minor or patch upgrade there should be none.
Test against a development database first. A release may include database migrations that BigLedger applies at startup.
Deploy.

// Before
implementation("com.bigledger:akaun-api:1.0.0")
implementation("com.bigledger:javasdk:1.0.0")

// After
implementation("com.bigledger:akaun-api:1.1.0")
implementation("com.bigledger:javasdk:1.1.0")

There is no merge step, and no BigLedger source in your repository that could conflict.

Database migrations run at startup and are not reversible. Once a newer release has upgraded a database schema, an older application version may no longer run against it. Take a backup before upgrading a production environment, and never test a new release against a production database.

What success looks like

Thirty seconds after the application starts on the new version.

One version, three artifacts. ./gradlew dependencies --configuration runtimeClasspath | grep com.bigledger lists akaun-api, javasdk and client-sdk at the same number. A different number on any line is the mixed-version case above, and it is not supported.
The schema migrated. The startup log carries Liquibase running liquibase-changelog-main.xml. In the database, SELECT MAX(dateexecuted) FROM databasechangelog; is later than the moment you started the application. If it is not, the application is talking to a different database from the one you upgraded.
The application answers. One authenticated GET against an endpoint you already use returns "code": "OK_RESPONSE" — the same response it gave before the upgrade.

If step 1 fails, fix the versions before anything else; a mixed classpath produces failures that look like product bugs. If step 2 shows no new row on a release that contained migrations, the application is running against a stale connection string. If step 3 returns CLIENT_AUTH_*, the upgrade is fine and the credential is not — see Authentication.

What is stable and what is not

Area	Treat as
REST API paths and payloads	The published surface — the API Reference is generated from the controllers of a named commit, so you can diff it release to release
Table and container classes in `client-sdk`	The published surface — `client-sdk` exists to be compiled against
Domain service and unit-of-work signatures	Usable, but internal in character; expect movement at a major release
Anything else on the classpath	Internal — may change in any release

BigLedger has not published a compatibility commitment, so nothing in the table above is a promise about what a minor release will and will not break. What is fixed is the release mechanics: the three artifacts always carry one version number, and a published version is never replaced. Build your upgrade process on compiling and testing, not on the version number alone, and ask BigLedger before you depend on a signature that is not in the API Reference or in client-sdk.

The safest code depends on documented, public entry points. The more deeply you reach into internals, the more work a major upgrade becomes.

Staying current

Take patch releases quickly — they carry fixes, including security fixes. Take minor releases on a regular cadence rather than saving several up. Plan major releases as a piece of work with time allocated for it.

The larger the gap between your version and the current one, the more expensive each upgrade becomes. Teams that upgrade every few weeks rarely spend more than minutes on it.