[airflow] 31/45: Update description of installing providers separately from core (#24454)

[ep...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

ephraimanierobi pushed a commit to branch v2-3-test
in repository https://gitbox.apache.org/repos/asf/airflow.git

commit 45216e51f2e3bb828c8be7d154f66f6960ee0c3c
Author: Jarek Potiuk <ja...@polidea.com>
AuthorDate: Mon Jun 20 10:09:56 2022 +0200

    Update description of installing providers separately from core (#24454)
    
    The description of how to install providers separately from the
    core was wrong. It suggested installing main constraints, but
    in fact we are not able to give any guarantees when installing
    providers this way so no constraints can guarantee consistent
    set of dependencies and the user is on their own in this case.
    
    This PR corrects the installation docs.
    
    (cherry picked from commit 28d3236202b34719020f9f7eb702af4d2f95a864)
---
 .../installation/installing-from-pypi.rst          | 36 +++++++++-------------
 1 file changed, 15 insertions(+), 21 deletions(-)

diff --git a/docs/apache-airflow/installation/installing-from-pypi.rst b/docs/apache-airflow/installation/installing-from-pypi.rst
index 51b9d7c044..3ec492b0ed 100644
--- a/docs/apache-airflow/installation/installing-from-pypi.rst
+++ b/docs/apache-airflow/installation/installing-from-pypi.rst
@@ -127,33 +127,27 @@ being installed.
     CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-${AIRFLOW_VERSION}/constraints-${PYTHON_VERSION}.txt"
     pip install "apache-airflow[postgres,google]==${AIRFLOW_VERSION}" --constraint "${CONSTRAINT_URL}"
 
-Installation and upgrading of Airflow providers separately
-==========================================================
+Installing/upgrading/downgrading providers separately from Airflow core
+=======================================================================
 
-You can manually install all the providers you need. You can continue using the "providers" constraint files
-but the 'versioned' airflow constraints installs only the versions of providers that were available in PyPI at
-the time of preparing of the airflow version. However, usually you can use "main" version of the providers
-to install latest version of providers. Usually the providers work with most versions of Airflow, if there
-will be any incompatibilities, it will be captured as package dependencies.
+In order to add new features, implement bug-fixes or simply maintain backwards compatibility, you might need
+to install, upgrade or downgrade any of the providers you need. We release providers independently from the
+core of Airflow, so often new versions of providers are released before Airflow is, also if you do not want
+yet to upgrade Airflow to the latest version, you might want to install newly released providers separately.
+For installing the providers you should not use any constraint files (the constraints are for installing
+Airflow with providers, not to install providers separately).
 
-Note that "main" is just an example - you might need to choose a specific airflow version to install providers
-in specific version.
+You should run provider's installation as a separate command after Airflow has been installed (usually
+with constraints). Constraints are only effective during the ``pip install`` command they were used with.
 
 .. code-block:: bash
 
-    PYTHON_VERSION="$(python --version | cut -d " " -f 2 | cut -d "." -f 1-2)"
-    # For example: 3.7
-    CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-main/constraints-${PYTHON_VERSION}.txt"
-    pip install "apache-airflow-providers-google" --constraint "${CONSTRAINT_URL}"
+    pip install "apache-airflow-providers-google==8.0.0"
 
-You can also upgrade the providers to latest versions (you need to use main version of constraints for that):
-
-.. code-block:: bash
-
-    PYTHON_VERSION="$(python --version | cut -d " " -f 2 | cut -d "." -f 1-2)"
-    # For example: 3.7
-    CONSTRAINT_URL="https://raw.githubusercontent.com/apache/airflow/constraints-main/constraints-${PYTHON_VERSION}.txt"
-    pip install "apache-airflow-providers-google" --upgrade --constraint "${CONSTRAINT_URL}"
+Note, that installing, upgrading, downgrading providers separately is not guaranteed to work with all
+Airflow versions or other providers. Some providers have minimum-required version of Airflow and some
+versions of providers might have conflicting requirements with Airflow or other dependencies you
+might have installed.
 
 
 Installation and upgrade of Airflow core