[airflow] branch master updated: Document Airflow's versioning and release policy for users (#14132)

[as...@apache.org]

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

ash pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/airflow.git


The following commit(s) were added to refs/heads/master by this push:
     new 3a80b70  Document Airflow's versioning and release policy for users (#14132)
3a80b70 is described below

commit 3a80b7076da8fbee759d9d996bed6e9832718e55
Author: Ash Berlin-Taylor <as...@firemirror.com>
AuthorDate: Thu Apr 1 14:29:14 2021 +0100

    Document Airflow's versioning and release policy for users (#14132)
    
    This document aims to show users what they can expect and rely upon from
    Airflow versions.
    
    It is far from complete and we will build it up over time, but creating
    the document from scratch is the hard part!
---
 docs/apache-airflow/index.rst           |  1 +
 docs/apache-airflow/release-process.rst | 83 +++++++++++++++++++++++++++++++++
 2 files changed, 84 insertions(+)

diff --git a/docs/apache-airflow/index.rst b/docs/apache-airflow/index.rst
index b02deaf..0d27443 100644
--- a/docs/apache-airflow/index.rst
+++ b/docs/apache-airflow/index.rst
@@ -99,6 +99,7 @@ unit of work and continuity.
     dag-serialization
     modules_management
     smart-sensor
+    Release policies <release-process>
     changelog
     best-practices
     production-deployment
diff --git a/docs/apache-airflow/release-process.rst b/docs/apache-airflow/release-process.rst
new file mode 100644
index 0000000..f389854
--- /dev/null
+++ b/docs/apache-airflow/release-process.rst
@@ -0,0 +1,83 @@
+ .. 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.