# Versions and compatibility

How ARX.SDK numbers its releases, what each kind of release may change, and how a change reaches you before it lands.

## One version for every package

The six packages (`ARX.SDK` and the five providers) are released together with one version, so a provider always works
with the core of the same version. Install the same version of each.

## What a release may change

| Release | Example | What may change |
|---|---|---|
| A preview | `0.1.0-preview.N` | Anything, from one preview to the next. Every change that can break code is listed under **Breaking** in the Version history, with what to do |
| A release candidate | `1.0.0-rc.N` | Fixes only: the public surface of 1.0.0 is fixed at `rc.1` (the API freeze). A fix that can't be made without a breaking change gets a new `rc` and says so under **Breaking** |
| A minor release before 1.0 | `0.2.0` | Breaking changes, listed under **Breaking** |
| A patch release | `0.2.1` | Fixes only: no breaking change |
| From 1.0 | `1.3.0`, `2.0.0` | A breaking change only in a major release (`2.0.0`); minor releases add, patches fix |

Versions follow [Semantic Versioning](https://semver.org/): a preview (`-preview.N`) promises no compatibility, and before
1.0 the minor number plays the major's part.

## How a change reaches you

- **Version history** lists every version, newest first, with its date and its Added, Changed, Fixed and Breaking
  entries. Each package carries the same entries in its `CHANGELOG.md`.
- **Issues and Resolutions** lists each known issue with its status: open, with what to do meanwhile; fixed, with the
  version that ships the fix.
- **Deprecation, from 1.0:** an API that will go is marked `[Obsolete]` with what to use instead for at least one minor
  release before a major release removes it.

## Choosing a version

Use the newest release, the top entry of the Version history. Read its Breaking entries before you upgrade from an
earlier one, and pin the exact version (`dotnet add package ARX.SDK.PostgreSql --version` and that version):
`dotnet add package` picks only stable versions by itself.

## Supported driver versions

Each provider is built against the lowest driver version it supports and allows any later one. NuGet resolves the
version your application references, so ARX uses the same driver as the rest of your code (EF Core 10 on PostgreSQL brings
Npgsql 10, for example).

| Package | Driver | Tested on |
|---|---|---|
| ARX.SDK.PostgreSql | Npgsql 8.0.3 or later | 8.0.3 and 10.0.3, the whole test suite on each |
| ARX.SDK.SQL | Microsoft.Data.SqlClient 7.1.1 or later | 7.1.1 |
| ARX.SDK.MySQL | MySqlConnector 2.6.2 or later | 2.6.2 |
| ARX.SDK.MongoDb | MongoDB.Driver 3.13.0 or later | 3.13.0 |
| ARX.SDK.DynamoDb | AWSSDK.DynamoDBv2 4.0.110 or later | 4.0.110 |

ARX reads values with explicit types, so a driver's change of default (Npgsql 10 reads `date` as `DateOnly`) doesn't
change what ARX returns.