From fa1533a693771cfcb947b62fe72c317077b9ce76 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Thu, 13 Nov 2025 15:46:46 +0200
Subject: [PATCH 1/4] Document release-cycle.json and python-releases.json

---
 peps/api/index.rst | 88 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 88 insertions(+)

diff --git a/peps/api/index.rst b/peps/api/index.rst
index 03cbc46d5be..1d754ac67d3 100644
--- a/peps/api/index.rst
+++ b/peps/api/index.rst
@@ -1,6 +1,9 @@
 PEPs API
 ========
 
+peps.json
+---------
+
 There is a read-only JSON document of every published PEP available at
 https://peps.python.org/api/peps.json.
 
@@ -102,3 +105,88 @@ illustrating some of the possible values for each field:
        "url": "https://peps.python.org/pep-3124/"
      }
    }
+
+release-cycle.json
+------------------
+
+There is a read-only JSON document of Python releases since version 2.6
+available at https://peps.python.org/api/release-cycle.json.
+
+For example:
+
+.. code-block:: json
+
+   {
+     "3.15": {
+       "branch": "main",
+       "pep": 790,
+       "status": "feature",
+       "first_release": "2026-10-01",
+       "end_of_life": "2031-10",
+       "release_manager": "Hugo van Kemenade"
+     },
+     "3.14": {
+       "branch": "3.14",
+       "pep": 745,
+       "status": "bugfix",
+       "first_release": "2025-10-07",
+       "end_of_life": "2030-10",
+       "release_manager": "Hugo van Kemenade"
+     }
+   }
+
+python-releases.json
+--------------------
+
+A more complete JSON document of all Python releases since version 1.6 is
+available at https://peps.python.org/api/python-releases.json and includes
+metadata about each feature release cycle, for example:
+
+.. code-block:: json
+
+   {
+     "metadata": {
+       "3.14": {
+         "pep": 745,
+         "status": "bugfix",
+         "branch": "3.14",
+         "release_manager": "Hugo van Kemenade",
+         "start_of_development": "2024-05-08",
+         "feature_freeze": "2025-05-07",
+         "first_release": "2025-10-07",
+         "end_of_bugfix": "2027-10-07",
+         "end_of_life": "2030-10-01"
+       }
+     }
+   }
+
+
+And also detailed information about each individual release within that cycle,
+for example:
+
+.. code-block:: json
+
+   {
+     "releases": {
+       "3.14": [
+         {
+           "stage": "3.14.0 candidate 3",
+           "state": "actual",
+           "date": "2025-09-18",
+           "note": ""
+         },
+         {
+           "stage": "3.14.0 final",
+           "state": "actual",
+           "date": "2025-10-07",
+           "note": ""
+         },
+         {
+           "stage": "3.14.1",
+           "state": "expected",
+           "date": "2025-12-02",
+           "note": ""
+         }
+       ]
+     }
+   }

From 7f53b357cef29ab4803973fa824cd71bbf1848f2 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 14 Nov 2025 14:32:04 +0200
Subject: [PATCH 2/4] Include the schema

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
---
 peps/api/index.rst | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/peps/api/index.rst b/peps/api/index.rst
index 1d754ac67d3..dc9da5b033a 100644
--- a/peps/api/index.rst
+++ b/peps/api/index.rst
@@ -112,6 +112,23 @@ release-cycle.json
 There is a read-only JSON document of Python releases since version 2.6
 available at https://peps.python.org/api/release-cycle.json.
 
+Each feature version is represented as a JSON object,
+keyed by the minor version number ("X.Y").
+The structure of each JSON object is as follows:
+
+.. code-block:: typescript
+
+   {
+     "<language version number>": {
+       "branch": string,
+       "pep": integer,
+       "status": 'feature' | 'prerelease' | 'bugfix' | 'security' | 'end-of-life',
+       "first_release": string,  // Date formatted as YYYY-MM-DD
+       "end_of_life": string,  // Date formatted as YYYY-MM-DD
+       "release_manager": string
+     },
+}
+
 For example:
 
 .. code-block:: json

From 1ef4eaec486d18d47798e2d8758e583f2979da96 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 14 Nov 2025 14:35:17 +0200
Subject: [PATCH 3/4] Fix indent

---
 peps/api/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/peps/api/index.rst b/peps/api/index.rst
index dc9da5b033a..789a93edafe 100644
--- a/peps/api/index.rst
+++ b/peps/api/index.rst
@@ -127,7 +127,7 @@ The structure of each JSON object is as follows:
        "end_of_life": string,  // Date formatted as YYYY-MM-DD
        "release_manager": string
      },
-}
+   }
 
 For example:
 

From a777de6a07481c19b803feb4ce6373b2ac3eaa63 Mon Sep 17 00:00:00 2001
From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
Date: Fri, 14 Nov 2025 14:38:09 +0200
Subject: [PATCH 4/4] Don't commit to "since 2.6"

---
 peps/api/index.rst | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/peps/api/index.rst b/peps/api/index.rst
index 789a93edafe..0ba9e778d77 100644
--- a/peps/api/index.rst
+++ b/peps/api/index.rst
@@ -109,7 +109,7 @@ illustrating some of the possible values for each field:
 release-cycle.json
 ------------------
 
-There is a read-only JSON document of Python releases since version 2.6
+There is a read-only JSON document of Python releases
 available at https://peps.python.org/api/release-cycle.json.
 
 Each feature version is represented as a JSON object,