From 9b8679a33f9299183d45fb0874a7a2dfbfd15222 Mon Sep 17 00:00:00 2001 From: Ulada Zakharava Date: Mon, 16 Dec 2024 15:20:48 +0000 Subject: [PATCH] Add deprecation policy --- .../deprecation-policy.rst | 57 +++++++++++++++++++ .../apache-airflow-providers-google/index.rst | 1 + 2 files changed, 58 insertions(+) create mode 100644 docs/apache-airflow-providers-google/deprecation-policy.rst diff --git a/docs/apache-airflow-providers-google/deprecation-policy.rst b/docs/apache-airflow-providers-google/deprecation-policy.rst new file mode 100644 index 0000000000000..7f3809cf8852b --- /dev/null +++ b/docs/apache-airflow-providers-google/deprecation-policy.rst @@ -0,0 +1,57 @@ + + .. Licensed to the Apache Software Foundation (ASF) under one + or more contributor license agreements. See the NOTICE file + distributed with this work for additional information + regarding copyright ownership. The ASF licenses this file + to you under the Apache License, Version 2.0 (the + "License"); you may not use this file except in compliance + with the License. You may obtain a copy of the License at + + .. http://www.apache.org/licenses/LICENSE-2.0 + + .. Unless required by applicable law or agreed to in writing, + software distributed under the License is distributed on an + "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + KIND, either express or implied. See the License for the + specific language governing permissions and limitations + under the License. + + .. NOTE! THIS FILE IS AUTOMATICALLY GENERATED AND WILL BE + OVERWRITTEN WHEN PREPARING PACKAGES. + + .. IF YOU WANT TO MODIFY THIS FILE, YOU SHOULD MODIFY THE TEMPLATE + `PROVIDER_CHANGELOG_TEMPLATE.rst.jinja2` IN the `dev/breeze/src/airflow_breeze/templates` DIRECTORY + +Deprecation policy for apache-airflow-providers-google package +---------------------------------------------------------------- + +Versioning of the package +````````````````````````` + +As mentioned in `Airflow's release process and version policy `__ +Google provider package (and others) should follow SemVer, meaning that any breaking changes should be released together with bumping major version of the package. +The change is considered to be a breaking if a DAG that was working before stops to work after the change. + +Deprecation Procedure +````````````````````` + +The entire procedure of deprecating (either method, parameter or operator) consists of two steps: + - Using decorator to mark an object as deprecated, specifying planned removal date and an object that can be used instead of deprecated one: + + .. code-block:: python + + from airflow.providers.google.common.deprecated import deprecated + + @deprecated( + planned_removal_date="September 30, 2025", + use_instead="airflow.providers.google.cloud.hooks.vertex_ai.auto_ml.AutoMLHook, " + category=AirflowProviderDeprecationWarning, + ) + + + - Once the date of the deprecated method/parameter/operator is passed, it can be removed together with bumping major version of the package. + +Additional Considerations +````````````````````````` + - Bumping a major version of the Airflow google provider package will happen once a month and everything that reached its deprecation removal date will be removed. + - By default all deprecations should allow a 6 months time period until they will be removed and not available. This period will give Airflow users enough time and flexibility to update their DAGs before actual removal happens. On a case by case basis this period can be adjusted given specific circumstances (e.g. in case deprecation is because of underlying API sunset which can happen earlier than in 6 months). diff --git a/docs/apache-airflow-providers-google/index.rst b/docs/apache-airflow-providers-google/index.rst index 37c428adf8137..84dd269549050 100644 --- a/docs/apache-airflow-providers-google/index.rst +++ b/docs/apache-airflow-providers-google/index.rst @@ -27,6 +27,7 @@ Home Changelog Security + Deprecation policy .. toctree:: :hidden: