01cd16654e
Co-authored-by: devin-ai-integration[bot] <158243242+devin-ai-integration[bot]@users.noreply.github.com>
40 lines
2.1 KiB
Markdown
40 lines
2.1 KiB
Markdown
# Airbyte Protocol Versioning
|
|
|
|
## Goal
|
|
|
|
The goal of this document is to define our approach to protocol changes.
|
|
|
|
We need a compromise between frequent breaking changes that are heavy on operations and infinite backward compatibility which is a burden from a software engineering point of view.
|
|
|
|
## Versioning Scheme
|
|
|
|
We are using a `<MAJOR>.<MINOR>.<PATCH>` scheme for the Protocol Versioning. (see [SemVer](https://semver.org/)).
|
|
|
|
We increment the
|
|
|
|
- MAJOR version when you make incompatible protocol changes
|
|
- MINOR version when you add functionality in a backwards compatible manner
|
|
- PATCH version when you make backwards compatible bug fixes
|
|
|
|
## Development Guidelines
|
|
|
|
1. We will continue to do our best effort to avoid introducing breaking changes to the Airbyte Protocol.
|
|
2. When introducing a new minor version of the Airbyte Protocol, new fields must come with sensible defaults for backward compatibility within the same major version, or be entirely optional.
|
|
3. When introducing a new major version of the Airbyte Protocol, all connectors from the previous major version will continue to work. This requires the ability to “translate” messages between 1 major version of the Airbyte Protocol.
|
|
|
|
## Safeguards
|
|
|
|
To ensure continuous operation, we have a few safeguards to prevent breaking existing configuration through protocol version incompatibilities.
|
|
|
|
### When upgrading Airbyte
|
|
|
|
When removing support for older versions of the Protocol, there is a risk removing the support for a version that is currently used.
|
|
|
|
To mitigate this, as part of the pre-upgrade checks that happens in the `airbyte-bootloader`, we verify that any connector currently part of an active connection will still be supported after the upgrade.
|
|
|
|
If any connector fails this check, we abort the upgrade and the `airbyte-bootloader` logs contains a list of connectors to upgrade. Those connectors will need to be upgraded from the UI before the platform itself can be upgraded.
|
|
|
|
### When upgrading a Connector
|
|
|
|
When upgrading a Connector from the UI, we will verify that the Protocol Version is supported before finalizing the Connector upgrade.
|