From ac42d4e7eb32d2039c23358ff16061a2f11d009d Mon Sep 17 00:00:00 2001
From: acoulton <andrew@ingenerator.com>
Date: Mon, 11 Nov 2024 20:05:16 +0000
Subject: [PATCH] feature: Adopt a release & PHP / dependency version support
 policy

---
 _themes/borg/layout.html                  |  3 +-
 _themes/borg/static/css/documentation.css | 25 ++++++-
 conf.py                                   |  2 +
 guides.rst                                |  1 +
 releases.rst                              | 84 +++++++++++++++++++++++
 5 files changed, 113 insertions(+), 2 deletions(-)
 create mode 100644 releases.rst

diff --git a/_themes/borg/layout.html b/_themes/borg/layout.html
index 0f67c37..57ebf5a 100644
--- a/_themes/borg/layout.html
+++ b/_themes/borg/layout.html
@@ -27,7 +27,8 @@
                    href="https://github.com/search?o=desc&q=behat+extension+in%3Aname%2Cdescription&ref=searchresults&s=stars&type=Repositories&utf8=%E2%9C%93">
                     Extensions
                 </a>
-                <a class="section" href="https://github.com/Behat/Behat/blob/master/CHANGELOG.md#change-log">
+                <a class="section {% if pagename == 'releases' %}active{% endif %}"
+                   href="{{ pathto('releases') }}">
                     Releases
                 </a>
                 <div class="section search" role="search">
diff --git a/_themes/borg/static/css/documentation.css b/_themes/borg/static/css/documentation.css
index 6f2a127..e2dc4ff 100644
--- a/_themes/borg/static/css/documentation.css
+++ b/_themes/borg/static/css/documentation.css
@@ -218,7 +218,8 @@ body > section {
 .text .note,
 .text .sidebar,
 .text .tip,
-.text img {
+.text img,
+table.docutils {
   margin-bottom: 20px;
 }
 
@@ -493,3 +494,25 @@ body > section {
 .text .next dt, .text .next dd {
   text-align: right;
 }
+
+table.docutils {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+table.docutils th {
+    font-weight: 600;
+}
+
+table.docutils th, table.docutils td {
+  padding: 6px 13px;
+  border: 1px solid #d1d9e0;
+}
+
+table.docutils tr:nth-child(2n) {
+  background-color: #f6f8fa;
+}
+
+table.docutils td > p, table.docutils th > p {
+  margin-bottom: 0;
+}
diff --git a/conf.py b/conf.py
index 9b447a3..50af688 100644
--- a/conf.py
+++ b/conf.py
@@ -7,6 +7,8 @@
 lexers['php'] = PhpLexer(startinline=True)
 extensions = [
    'notfound.extension',
+   # Enables automatic linking to headings within the document within Sphinx
+   'sphinx.ext.autosectionlabel'
 ]
 
 source_suffix = '.rst'
diff --git a/guides.rst b/guides.rst
index ecf6489..8b549c0 100755
--- a/guides.rst
+++ b/guides.rst
@@ -70,6 +70,7 @@ and the same.
    quick_start
    user_guide
    cookbooks
+   releases
    useful_resources
    community
 
diff --git a/releases.rst b/releases.rst
new file mode 100644
index 0000000..5dd60a0
--- /dev/null
+++ b/releases.rst
@@ -0,0 +1,84 @@
+Releases & version support
+==========================
+
+Behat follows `Semantic Versioning`_ - breaking changes will only be made in a major release.
+
+Supported versions
+------------------
+
+======= ========== ========== ============ =====================================================================
+Major   Released   Bugfix EOL Security EOL
+======= ========== ========== ============ =====================================================================
+`v3.x`_ April 2014 See below  See below    `Changelog <https://github.com/Behat/Behat/blob/master/CHANGES.md>`__
+======= ========== ========== ============ =====================================================================
+
+As a minimum, a major version series will receive:
+
+* Bugfixes for 12 months after the release of the next major.
+* Security fixes for 24 months after the release of the next major.
+
+Each time a new major version is released, the Behat maintainers will set End-of-Life dates for the previous version
+series. This will be based on the scale of the breaking changes, the complexity of supporting the older version, and the
+likely effort required for users and third-party extensions to upgrade.
+
+Bugfixes will usually only be applied to the most recent minor of each supported major version, unless they are
+particularly severe or have security implications. This will impact
+:ref:`support for End-of-Life PHP & symfony versions<Support for PHP and dependency versions>`.
+
+Release timescales
+------------------------------
+
+There is no fixed schedule for releasing new major versions - but we will try to keep them to a frequency that is
+manageable for users.
+
+Minor versions
+~~~~~~~~~~~~~~
+
+Minor & patch versions will be released whenever there is something to release. These releases do not come with any
+specific support timescale, and we expect that users will upgrade to the next minor when it becomes available.
+
+Please bear in mind that this is free software, maintained by volunteers as a gift to users, and the license
+specifically explains that it is provided without warranty of any kind.
+
+
+Support for PHP and dependency versions
+---------------------------------------
+
+Behat only supports current versions of PHP and third-party dependency packages (e.g. symfony components).
+
+By "current", we mean:
+
+* PHP versions that are listed as receiving active support or security fixes on the `official php.net version support page`_.
+* Symfony versions that are listed as maintained or receiving security fixes on the `official symfony releases page`_.
+
+Once a PHP or symfony version reaches End of Life we will remove it from our composer.json and CI flows.
+
+.. note::
+   When we drop support for a PHP / dependency version we will highlight this in the CHANGELOG, but we will treat
+   it as a minor release. Composer will automatically protect users from upgrading to a version that does not support
+   their environment. Users running Behat as a `.phar` should review the release notes before downloading a new version.
+
+We will not ship bugfix releases for unsupported PHP / dependency versions, unless:
+
+* It fixes a security vulnerability within the security support period for a Behat major version.
+* An external contributor wishes to take on the work of backporting, including any changes required
+  to get a green build in CI.
+
+End-of-Life versions
+--------------------
+
+These behat series are no longer maintained and will not receive any further releases. We strongly recommend that users
+upgrade to a supported version as soon as possible.
+
+======= ========== ============ ============ =====================================================================
+Major   Released   Bugfix EOL   Security EOL
+======= ========== ============ ============ =====================================================================
+`v2.x`_ July 2011  June 2015    June 2015    `Changelog <https://github.com/Behat/Behat/blob/2.5/CHANGES.md>`__
+======= ========== ============ ============ =====================================================================
+
+
+.. _`Semantic Versioning`: http://semver.org/
+.. _`official php.net version support page`: https://www.php.net/supported-versions.php
+.. _`official symfony releases page`: https://symfony.com/releases
+.. _`v2.x`: https://github.com/Behat/Behat/releases?q=v2
+.. _`v3.x`: https://github.com/Behat/Behat/releases?q=v3