Add API version deprecation policy, Deprecation/Sunset headers, and end of support information (#61005)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>
Co-authored-by: Joe Clark <31087804+jc-clark@users.noreply.github.com>

Author: 4 people

content/rest/about-the-rest-api/api-versions.md

@@ -36,7 +36,7 @@ curl {% data reusables.rest-api.version-header %} https://api.github.com/zen
 
 Requests without the `X-GitHub-Api-Version` header will default to use the `{{ defaultRestApiVersion }}` version.
 
-If you specify an API version that is no longer supported, you will receive a `400` error.
+If you specify an API version that is no longer supported, you will receive a `410 Gone` response.
 
 ## Upgrading to a new API version
 
@@ -46,12 +46,45 @@ When you update your integration to specify the new API version in the `X-GitHub
 
 Once your integration is updated, test your integration to verify that it works with the new API version.
 
+## API version {% data variables.release-phases.closing_down %}
+
+API versions are supported for 24 months after a newer API version is released.
+
+While a version is within its support window but approaching  {% data variables.release-phases.closing_down %}, {% data variables.product.github %} includes the following headers in API responses to help you prepare for migration:
+
+* `Deprecation` — The date when the API version will be {% data variables.release-phases.closing_down %}, formatted as an HTTP date per [RFC 7231](https://tools.ietf.org/html/rfc7231#section-7.1.1.1). For example: `Wed, 27 Nov 2019 14:34:29 GMT`. <!-- markdownlint-disable-line GHD046 -->
+* `Sunset` — The date when the API version will be completely removed ({% data variables.release-phases.retired %}), after which requests will return a `410 Gone` response. Follows [RFC 8594](https://tools.ietf.org/html/rfc8594). For example: `Fri, 27 Nov 2020 14:34:29 GMT`. <!-- markdownlint-disable-line GHD046 -->
+
+After the support window ends:
+
+* Requests that specify a {% data variables.release-phases.closing_down %} API version receive a `410 Gone` response.
+* Requests that do not specify an API version default to the next oldest supported version, not the {% data variables.release-phases.closing_down %} version. If you rely on unversioned requests, you may observe behavioral changes as older versions are removed from support.
+
+For more information on migrating to a newer API version, see [AUTOTITLE](/rest/about-the-rest-api/breaking-changes).
+
+## Exceptions to standard versioning
+
+In rare cases, {% data variables.product.github %} may make changes outside the normal API versioning cadence. These are exceptional interventions that do not alter the standard versioning guarantees for most integrators.
+
+### Security, availability, and reliability issues
+
+Critical security vulnerabilities, data exposure risks, or severe reliability issues may require changes outside the normal release schedule. {% data variables.product.github %} may release an unscheduled API version, backport fixes to supported versions, or in rare cases, introduce a breaking change to an existing version to protect users and platform integrity.
+
+{% data variables.product.github %} will communicate such changes through release notes, changelogs, and direct communication explaining what changed and why. Where feasible, advance notice will be provided. Immediate action may be taken without advance notice when required.
+
+### Low-usage services
+
+For certain services with very low usage, {% data variables.product.github %} may deprecate functionality outside the standard versioning process. In these cases, {% data variables.product.github %} will communicate the intent and reach out to affected integrators directly.
+
 ## Supported API versions
 
-The following REST API versions are currently supported:
+The following REST API versions are currently supported.
 
-{% for apiVersion in allVersions[currentVersion].apiVersions %}
-{{ apiVersion }}
-{% endfor %}
+| API version | End of support date |
+| --- | --- |
+{%- for apiVersion in allVersions[currentVersion].apiVersions %}
+{%- assign versionData = tables.rest-api-versions.versions[apiVersion] %}
+| `{{ apiVersion }}` | {{ versionData.end_of_support | default: "Not yet scheduled" }} |
+{%- endfor %}
 
 You can also make an API request to get all of the supported API versions. For more information, see [AUTOTITLE](/rest/meta/meta#get-all-api-versions).

data/reusables/rest-api/about-api-versions.md

@@ -1,6 +1,6 @@
 The {% data variables.product.github %} REST API is versioned. The API version name is based on the date when the API version was released. For example, the API version `{{ initialRestVersioningReleaseDate }}` was released on {{ initialRestVersioningReleaseDateLong }}.
 
-Breaking changes are changes that can potentially break an integration. We will provide advance notice before releasing breaking changes. Breaking changes include:
+Breaking changes are changes that can potentially break an integration. Breaking changes will be released in a new API version. We will provide advance notice before releasing breaking changes. Breaking changes include:
 
 * Removing an entire operation
 * Removing or renaming a parameter

data/tables/rest-api-versions.yml

@@ -0,0 +1,8 @@
+# REST API calendar date versions and their end of support dates.
+# Rendering code lives in content/rest/about-the-rest-api/api-versions.md
+
+versions:
+  '2022-11-28':
+    end_of_support: 'March 10, 2028'
+  '2026-03-10':
+    end_of_support: ~

src/data-directory/lib/data-schemas/tables/rest-api-versions.ts

@@ -0,0 +1,22 @@
+// This schema enforces the structure in data/tables/rest-api-versions.yml
+
+export default {
+  type: 'object',
+  additionalProperties: false,
+  required: ['versions'],
+  properties: {
+    versions: {
+      type: 'object',
+      additionalProperties: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['end_of_support'],
+        properties: {
+          end_of_support: {
+            type: ['string', 'null'],
+          },
+        },
+      },
+    },
+  },
+}