| .. 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. |
| |
| ========================= |
| Airflow's release process |
| ========================= |
| |
| Since Airflow 2.0.0 and provider packages 1.0.0 we aim to follow SemVer, meaning the release numbering works as follows: |
| |
| - Versions are numbered in the form X.Y.Z. |
| - X is the major version number. |
| - Y is the minor version number, also called the *feature release* version number. |
| - Z is the patch number, which is incremented for bugfix and security releases. |
| Before every new release, we’ll make a release candidate available, and often alpha or beta release too. |
| These are of the form X.Y.Z alpha/beta/rc N, which means the Nth alpha/beta/release candidate of version X.Y.Z |
| |
| In git, each minor version will have its own branch, called ``vX-Y-stable`` where bugfix/security releases will be issued from. |
| Commits and PRs should not normally go direct to these branches, but instead should target the main branch and then be cherry-picked by the release managers to these release branches. |
| |
| Each Airflow release will also have a tag in git indicating its version number, signed with the release manager's key. |
| Tags for the main Airflow release have the form ``X.Y.Z`` (no leading ``v``) and provider packages are tagged with the form ``providers-<name>/X.Y.Z``. |
| |
| Although Airflow follows SemVer this is not a promise of 100% compatibility between minor or patch releases, simply because this is not possible: what is a bug to one person might be a feature another person is depending on. |
| |
| Knowing the *intentions* of a maintainer can be valuable – especially *when* things break. Because that's all SemVer is: **a TL;DR of the changelog**. |
| |
| -- Hynek Schlawack https://hynek.me/articles/semver-will-not-save-you/ |
| |
| That is all SemVer is -- it's a statement of our intent as package authors, and a clear statement of our goals. |
| |
| .. glossary:: |
| |
| Major release |
| Major releases (X.0.0, X+1.0.0 etc.) indicate a backwards-incompatible change. |
| |
| These releases do not happen with any regular interval or on any predictable schedule. |
| |
| Each time a new major version is released previously deprecated features will be removed. |
| |
| Feature releases |
| Feature releases (X.Y.0, X.Y+1.0, etc.) will happen roughly every two or three months – see release process for details. |
| These releases will contain new features, improvements to existing features, and such. |
| |
| Patch releases |
| Patch releases (X.Y.Z, X.Y.Z+1, etc.) will happen, on an as-needed basis, as issues are reported and fixed. |
| |
| These releases will be 100% compatible with the associated feature release. |
| So the answer to "should I upgrade to the latest patch release?" will always be "yes." |
| |
| The only exception to the above with respect to 100% backwards compatibility is when a security or data loss issue can’t be fixed without breaking backwards-compatibility. |
| If this happens, the release notes will provide detailed upgrade instructions. |
| **No new features will be added in patch releases** |
| |
| |
| Deprecation policy |
| ================== |
| |
| From time-to-time existing features will be deprecated, or modules will be renamed. |
| |
| When this happens, the existing code will continue to work but will issue a DeprecationWarning (or a subclass) when the code is executed. |
| This code will continue to work for the rest of the current major version -- if it works on 2.0.0, it will work for every 2.Y.Z release. |
| |
| So, for example, if we decided to start the deprecation of a function in Airflow 2.2.4: |
| |
| * Airflow 2.2 will contain a backwards-compatible replica of the function which will raise a DeprecationWarning |
| * Airflow 2.3 will continue to work and issue a warning |
| * Airflow 3.0 (the major version that follows 2.2) will remove the feature outright |
| |
| The exception to this deprecation policy is any feature which is marked as "experimental", which *may* suffer breaking changes or complete removal in a Feature release. |