# Versions and compatibility in AWS Emulator
<a name="versioning"></a>

We aim to keep breaking changes rare, so that your tests keep working when you upgrade. This topic explains version numbers, what you can rely on, and how fidelity fixes can change your test results.

**Topics**
+ [Version numbers](#versioning-numbers)
+ [Finding and installing a specific version](#versioning-list)
+ [Security fixes](#versioning-security)
+ [What stays compatible](#versioning-compatible)
+ [How fidelity changes affect your tests](#versioning-fidelity)

## Version numbers
<a name="versioning-numbers"></a>

 AWS Emulator versions use the format `MAJOR.MINOR.PATCH`:
+  **MAJOR** – Changes that can break how you start, configure, or connect to the emulator. Examples are a removed or renamed option, environment variable, or control route.
+  **MINOR** – New features that don’t break how you start, configure, or connect to the emulator, such as new options or new control routes.
+  **PATCH** – Bug fixes and fidelity fixes.

To see your version, run the following command.

```
aws-emulator -v
```

The command prints three lines:
+  `Version` – The version of the emulator
+  `Release date` – The date of the release
+  `Commit` – The GitHub commit for the build

## Finding and installing a specific version
<a name="versioning-list"></a>

Packages are published under the following address. The latest packages are in the `latest/` folder.

```
https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/
```

For the list of published versions, see the following file.

```
https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/versions.json
```

To install a specific version, put the version in the package file name. Replace `<version>` with a version from the list:
+  **RPM package (x86\_64)** – `https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator-<version>-1-x86_64.rpm` 
+  **RPM package (aarch64)** – `https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator-<version>-1-aarch64.rpm` 
+  **Debian package (amd64)** – `https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator_<version>-1_amd64.deb` 
+  **Debian package (arm64)** – `https://downloads.aws.com/aws-emulator/packages/aws-emulator/LTS/aws-emulator_<version>-1_arm64.deb` 

Install the package the same way as the latest release, as shown in [To install AWS Emulator](getting-started-linux.md#getting-started-linux-install).

We recommend that you use the latest version. If a new release changes your test results, see [How fidelity changes affect your tests](#versioning-fidelity).

## Security fixes
<a name="versioning-security"></a>

We publish security fixes only in the latest release. Older releases don’t get fixes. To get them, upgrade to the latest release.

A security fix might need a breaking change, even within a major version. For example, an operation that works without credentials might start to need them.

## What stays compatible
<a name="versioning-compatible"></a>

Within a major version, these stay the same:
+ The `aws-emulator` command, its options, and their default values
+ The environment variables in this guide
+ The emulator control routes, such as the health check
+ The package URLs on `downloads.aws.com` 
+ The startup line of the log and its fields, which give the address and port that the emulator serves on

Don’t rely on the following. They can change in any release:
+ The fields in log output, other than the startup line. The emulator writes its log as JSON lines, but the rest of the log isn’t a stable interface.
+ The content of the `-h` help text
+ Files in the emulator’s local directories, other than the ones in this guide
+ The size and format of the credentials that the emulator generates
+ What’s in the installation package, other than the `aws-emulator` command and the license and notice files

## How fidelity changes affect your tests
<a name="versioning-fidelity"></a>

We test each release against the fidelity tests in the [aws-emulator-evaluation-suite repository on GitHub](https://github.com/aws/aws-emulator-evaluation-suite). We publish the scores for each service with each release, with the version of the fidelity tests that we used. For more information, see [Reading the fidelity scores](fidelity.md#fidelity-scores).
+  **Behavior that a passing fidelity test covers** – Fidelity tests that pass don’t regress.
+  **Behavior that no fidelity test covers** – A release can fix a response so it matches AWS. If your tests relied on the earlier response, they can start to fail.

The fidelity tests don’t cover every behavior yet. We’re continuously adding new fidelity tests based on customer feedback and fidelity issues that we discover. To learn how to check which behavior they cover, see [Checking whether your project works with AWS Emulator](check-project.md). To limit the effect of these changes:
+ If new releases change your test results, install a specific version, as described in [Finding and installing a specific version](#versioning-list). Then a new release changes your results only when you choose to upgrade. Test a new version before you upgrade.
+ Write tests that expect what AWS does, not what the emulator does today. As the emulator’s fidelity improves, it moves closer to AWS. For the APIs that matter to your app, also run your tests against AWS. For more information, see [Fidelity in AWS Emulator](fidelity.md).

If a patch release changes your test results, either the emulator now matches AWS more closely, or it’s a bug that you can report. Read the release notes on the [AWS Emulator releases page on GitHub](https://github.com/aws/aws-emulator/releases) before you move to a new minor or major version.

If a release makes the emulator act differently from AWS, tell us. For more information, see [Telling us about a difference](fidelity.md#fidelity-report).