This is an automated email from the ASF dual-hosted git repository.
potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/airflow.git
The following commit(s) were added to refs/heads/main by this push:
new bfb72025d7 Add description about breaking changes and bumping min dep
versions (#37239)
bfb72025d7 is described below
commit bfb72025d7e01565bf00a3e2ab678017e09932c9
Author: Jarek Potiuk <[email protected]>
AuthorDate: Thu Feb 8 11:03:10 2024 +0100
Add description about breaking changes and bumping min dep versions (#37239)
* Add description about breaking changes and bumping min dep versions
* Update contributing-docs/11_provider_packages.rst
Co-authored-by: Elad Kalif <[email protected]>
* Update 11_provider_packages.rst
---------
Co-authored-by: Elad Kalif <[email protected]>
---
contributing-docs/11_provider_packages.rst | 36 ++++++++++++++++++++++++++++++
1 file changed, 36 insertions(+)
diff --git a/contributing-docs/11_provider_packages.rst
b/contributing-docs/11_provider_packages.rst
index ffc6d40a3e..ec94c475a5 100644
--- a/contributing-docs/11_provider_packages.rst
+++ b/contributing-docs/11_provider_packages.rst
@@ -228,6 +228,42 @@ providers.
* System Tests which provide end-to-end testing, usually testing together
several operators, sensors,
transfers connecting to a real external system
+Breaking changes in the community managed providers
+---------------------------------------------------
+
+Sometimes we have to introduce breaking changes in the providers. We have to
be very careful with that
+and we have to make sure that we communicate those changes properly.
+
+Generally speaking breaking change in provider is not a huge problem for our
users. They can individually
+downgrade the providers to lower version if they are not ready to upgrade to
the new version and then
+incrementally upgrade to the new versions of providers. This is because
providers are installed as
+separate packages and they are not tightly coupled with the core of Airflow
and because we have a very
+generous policy of supporting multiple versions of providers at the same time.
All providers are in theory
+backward compatible with future versions of Airflow, so you can upgrade
Airflow and keep the providers
+at the same version.
+
+When you introduce a breaking change in the provider, you have to make sure
that you communicate it
+properly. You have to update ``CHANGELOG.rst`` file in the provider package
and you have to make sure that
+you update the ``provider.yaml`` file with the new (breaking) version of the
provider. Ideally in the
+``CHANGELOG.rst`` you should also provide a migration path for the users to
follow.
+
+If in doubt, you can always look at ``CHANGELOG.rst`` in other providers to
see how we communicate
+breaking changes in the providers.
+
+It's important to note that the marking release as breaking / major is subject
to the
+judgment of release manager upon preparing the release.
+
+Bumping minimum version of dependencies in providers
+----------------------------------------------------
+
+Generally speaking we are rather relaxed when it comes to bumping minimum
versions of dependencies in the
+providers. If there is a good reason to bump the minimum version of the
dependency, you should simply do it.
+This is because user might always install previous version of the provider if
they are not ready to upgrade
+the dependency (because for example another library of theirs is not
compatible with the new version of the
+dependency). In most case this will be actually transparent for the user
because ``pip`` in most cases will
+find and install a previous version of the provider that is compatible with
your dependencies that conflict
+with latest version of the provider.
+
------
You can read about airflow `dependencies and extras
<12_airflow_dependencies_and_extras.rst>`_ .
