Hi. I would like to discuss/propose a deprecation policy for apache-airflow-providers-google package, mostly for deprecating Airflow operators (but not limited to it).
*Some background:* Airflow google provider package (as most of other provider packages in Airflow) has a tendency to constantly evolve. There are cases when its features or operators/hooks have to be deprecated. The typical example of such a case is “refactoring” which leads to the renaming of operators, parameters or public methods. Such refactorings maybe consequence of: - using a new dependent library (that causes some methods to be deprecated) - using a new version of API (that causes some parameters to be deprecated) - restructuring/migration of the operators (that causes some operators to be deprecated) Given the need of a “deprecation” procedure, it looks essential to establish policy around it to have users of Airflow google provider package clearly understand when and how to adapt their DAGs. *Preambula (versioning of the package):* As mentioned in “Airflow’s release process and version policy” ( https://airflow.apache.org/docs/apache-airflow/stable/release-process.html#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 (in the context of google providers package) if a DAG that was working before, stops to work after the change. *My proposal (for discussion):* The entire procedure of deprecating (either method, parameter or operator) consists of two steps: - Emission of the deprecation warning message Example of the message: “”” The “given” parameter is deprecated and will be removed after dd.mm.yyyy. Please use “this” parameter instead. “”” - Once the date of the deprecated method/parameter/operator is passed, it can be removed (together with bumping major version of the package) The format of the warning message may vary, but it has to contain: - What should be used instead - The date after which the method/parameter/operator will be removed *Additional considerations:* - Bumping a major version of the Airflow google provider package shouldn’t happen very frequently (presumably not more frequently than 6 months), therefore when it happens it may accumulate removals of something that was communicated to be removed even a couple of months ago. (related discussion https://github.com/apache/airflow/blob/main/PROVIDERS.rst) Example: if today is 2025-12-20 and we are releasing new major version of the package, we can/should remove all deprecated methods/parameters/operators which have date prior to 2025-12-20 - it can be November 2025, October 2025 or even earlier, since previous bump of major version happened e.g. in summer of 2025. - 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). Apart from deprecation warning messages that will be printed as logs, this information will be put as well in: - Airflow documentation - Release notes of Airflow google provider package Please, let me know what you think about this. -- Eugene
