docs: add Package and Container Image Retention Policy

developer-support/retention-policy.mdx

@@ -0,0 +1,107 @@
+---
+title: Package and Container Image Retention Policy
+description: "Tyk's policy for how long published packages and container images stay available in public registries, and how retention windows are calculated."
+sidebarTitle: "Retention Policy"
+keywords: "Retention policy, Package retention, Container image retention, EOL"
+---
+
+This page explains how Tyk manages the lifecycle of published packages and container images: how retention windows are calculated for each edition and release track, and what to expect as older versions approach removal from our public registries.
+
+## Why We're Introducing This
+
+To maintain repository health and ensure users run secure, supported versions, we are formalizing our retention policy for software packages (DEB/RPM) and container images (Docker). Older, unsupported versions are not kept indefinitely in our public registries, but a version is never removed without advance notice.
+
+## When Do We Start Pruning?
+
+We start pruning from **1st December 2026**.
+
+## Our Release Tracks and Editions
+
+Tyk software is delivered via two primary release tracks:
+- **Long Term Support (LTS):** designed for maximum stability, predictability, and security in mission-critical production environments.
+- **Feature Releases:** designed for rapid innovation, giving you early access to the latest capabilities and product enhancements.
+
+Across these tracks, we offer distinct editions:
+- **Enterprise Edition (EE) & FIPS variants:** our fully-featured offering, requiring an enterprise license. Available as Docker images, RPM, and DEB packages, across the Feature, LTS, and LTS-1 release tracks.
+- **Community Edition (CE):** a focused feature set, available as Docker images, RPM, and DEB packages, on the **Feature release track only**. CE does not include the LTS or LTS-1 tracks.
+
+Community and Enterprise packages are currently published to the same public repositories (for example, tyk-gateway on PackageCloud and Docker Hub). In practice, this means a Community package remains available in public registries for as long as the Enterprise retention window below allows, even though Community's own window (see next section) is shorter.
+
+## How Retention Windows Are Calculated
+
+Retention windows are calculated against **version position** (how many supported minor releases back a version sits), rather than a fixed calendar date. This means the window tracks the real state of the release catalogue, independent of how fast or slow any given release cycle runs.
+
+### Community Edition (CE): Docker, RPM, DEB, Feature Track Only
+
+A CE package is scheduled for removal once the current Feature release advances two minor versions beyond it (**current minus 2 minors**).
+
+*Example:* if the current Feature release is 5.11.x, the retention floor is 5.9.x. Packages for 5.8.x and below are scheduled for removal.
+
+### Enterprise Edition (EE) & FIPS Variants: Docker, RPM, DEB
+
+An EE package is scheduled for removal once it falls below **LTS-1 minus 3 minors**. This single threshold governs all EE packages across every format and release track.
+
+*Example:* if the current LTS is 5.8.x and LTS-1 is 5.4.x, the retention floor is 5.1.x. Packages for 5.0.x and below are scheduled for removal.
+
+FIPS variants follow the same threshold as EE.
+
+### Pre-Release and Unstable Packages
+
+Alpha, beta, and release-candidate builds, across all editions, are purged automatically **90 days** after creation, regardless of version position. These builds are intended for testing only and should not be relied on for production use.
+
+<Note>
+There is no LTS track for Community Edition, so LTS-based retention does not apply to it. There is no archive or secondary access for CE. Once a Community package is independently removed under its own window, it is retired permanently.
+</Note>
+
+## Retention Trigger Summary
+
+| Edition | Formats | Track(s) | Prune trigger |
+|---|---|---|---|
+| Community (CE) | Docker, RPM, DEB | Feature only | Current Feature release minus 2 minors |
+| Enterprise (EE) | Docker, RPM, DEB | Feature, LTS, LTS-1 | LTS-1 minus 3 minors |
+| FIPS variants | Docker, RPM, DEB | Feature, LTS, LTS-1 | Same as EE |
+| Pre-release / unstable | All formats | All | 90 days after creation |
+
+## What Happens Before a Version Is Removed
+
+Every pruning event is announced before it happens. Notifications are triggered by version events, such as a new minor or LTS release, not by fixed calendar dates. The grace period you get to act is always predictable:
+
+- **Standard notice:** a 30-day grace period begins the moment a version crosses its retention threshold.
+- **First-time notice:** because this policy is new, we've given all affected customers **90 days** notice from our first pruning event. This communication included an opt-in option to subscribe to the standard notices.
+
+### Community Edition Notice Timeline
+
+| When | Channel | What you'll see |
+|---|---|---|
+| New minor ships (version becomes N-1) | Forum + Release Notes | "Version X is now one minor behind current. It will be removed when the next minor ships." |
+| Next minor ships (version becomes N-2, threshold crossed, 30-day grace begins) | Forum (pinned) + direct email* | "Version X has reached end of retention. Scheduled for permanent removal on [date + 30 days]." |
+| Removal date | Forum | "Removed." |
+
+*\* Direct email is sent to customers who have opted in to ongoing advance notices. See [Staying Informed](#staying-informed) below. Everyone sees the Forum and Release Notes updates regardless of opt-in status.*
+
+### Enterprise Edition Notice Timeline
+
+| When | Channel | What you'll see |
+|---|---|---|
+| Two minors from threshold | Account Manager check-in | "Version X is two minor releases from end of public retention. Any upgrade constraints we should know about?" |
+| One minor from threshold | Direct email* + Forum | "Version X is one minor release from end of public retention." Upgrade guide linked. |
+| Threshold crossed (30-day grace begins) | Direct email* + Account Manager | "Version X has crossed the retention threshold. Public removal on [date + 30 days]." |
+| 30 days after threshold crossed | Blog + Forum | "Removed from public registries." |
+
+*\* Direct email is sent to customers who have opted in to ongoing advance notices; all customers additionally see the Forum and Blog channels regardless of opt-in status.*
+
+## Staying Informed
+
+Opt in to receive a direct 30-day advance notice for every future retirement, instead of relying on forum posts and release notes.
+
+Opt in here: [pages.tyk.io/long-term-support](https://pages.tyk.io/long-term-support)
+
+## If You Need More Time
+
+Every environment is different, and we know upgrades take planning. If you'd like to keep running an older version for now, reach out to your Customer Success contact. They can talk through what that looks like for your setup and help you weigh the options.
+
+## What This Means for You
+
+If you're running a supported version of Tyk Enterprise Edition (at or above LTS-1 minus 3 minors), or a Community Edition version no more than 2 minor releases behind the current Feature release, no action is required today.
+
+We recommend staying on a current release regardless, to get the latest security fixes and the fastest support.

docs.json

@@ -91,7 +91,8 @@
                   "api-management/fips-implementation"
                 ]
               },
-              "developer-support/deprecation"
+              "developer-support/deprecation",
+              "developer-support/retention-policy"
             ]
           },
           {