
# Versions and compatibility

Java solves library conflicts with a BOM. pub resolves exactly one version of every package per application, so conflicts cannot hide at run time: `pub get` fails and names the culprits. What remains is keeping the family consistent and making incompatible starters readable.

## Why

An application depends on several starters, each built against some version of `spring_boot_dart`. A starter made for an older version may use an API that has changed. The check below stops the build with a clear message instead of a confusing compile error, or worse, a wrong behaviour at run time.

## Example

```dart
// lib/spring_auto_configuration.dart of a starter
@AutoConfigurationModule(requires: '^0.7.0')
final BeanModule neonCacheAutoConfiguration = $neonCacheBeans;
```

An application on `spring_boot_dart` 0.6.3 that adds this starter gets, from `build_runner`:

```text
Incompatible starter: neon_cache requires spring_boot_dart ^0.7.0, but 0.6.3 is used.
Upgrade spring_boot_dart to a version in ^0.7.0, or use a version of neon_cache made for spring_boot_dart 0.6.3.
```

## The rules

- **Release train.** `spring_core_dart`, `spring_core_dart_generator`, `spring_boot_dart` and the `spring_boot_starter_*` packages always share one version (0.7.1 at the time of writing) and depend on each other with `^<version>`. Use the same version for all of them.
- **No backward compatibility before 1.0.** Any release may rename or change APIs, properties and behaviour; the breaking changes are listed in each package's CHANGELOG.
- **`requires`** is a pub version range (`^0.7.0`, `'>=0.6.0 <0.8.0'`). The generator compares it with `springBootVersion` and stops the build on a mismatch. `null` (the default) accepts any version.
- **Wide third-party constraints.** Starters keep their constraints wide (`dio: '>=5.0.0 <7.0.0'`) so the solver finds a common version.
- **Escape hatch:** `dependency_overrides` in the application's `pubspec.yaml`, like overriding a managed version in Maven.

`springBootVersion` (a constant of `spring_boot_dart`) is the running version; `${spring-boot.version}` shows it in a banner.

## In Spring (Java)

Spring Boot's BOM and Spring Cloud's compatibility verifier do this job. Here pub's solver and the `requires` check at build time replace them.

## See also

- [Auto-configuration and starters](auto-configuration.md)
- [The generator: auto-configurations](../spring-core-dart-generator/auto-configurations.md)
