docs: add Package and Container Image Retention Policy

developer-support/retention-policy.mdx

@@ -0,0 +1,108 @@
+---
+title: Package and Container Image Retention Policy
+description: How we manage the lifecycle of our published packages and container images.
+---
+
+Welcome to Tyk's Package and Container Image Retention Policy. Here, we'll walk you through how we manage the lifecycle of our published packages and container images, how retention windows are calculated for each edition and release track, and what to expect — and do — as older versions approach removal from our public registries.
+
+## Why We're Introducing This
+
+APIs are the connective tissue of everything you build — and increasingly, the interface your automated workflows and AI agents rely on to retrieve data, trigger actions, and make decisions. That kind of autonomy, at that kind of scale, only works if the infrastructure underneath it is secure, current, and actively supported.
+
+To maintain repository health and ensure our users are running secure, supported versions, we are formalizing our retention policy for software packages (DEB/RPM) and container images (Docker). Older, unsupported versions will not be kept indefinitely in our public registries — but a version is never removed without clear 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 archiving and 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 archiving and 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 (never archived) |
+| 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 (a new minor or LTS release), not by fixed dates on the calendar, but 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 communicated to all affected customers **90 days'** 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
+
+You can opt in now to keep receiving these direct 30-day advance notices for every future retirement, rather than relying on our public forum posts and release notes to catch the change yourself.
+
+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 strongly encourage everyone to keep pace with current releases regardless: it's the simplest way to make sure your gateway carries every security fix and CVE patch we've shipped, and it means our Support team can help you faster, because they know exactly what you're running.
+
+And don't forget — our Customer Success Teams and Account Managers are here to help with any questions about where your deployment stands or what upgrading would involve.

docs.json

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

tyk-self-managed/install/docker.mdx

@@ -8,6 +8,10 @@ sidebarTitle: "Docker"
 | :------ | :-------------- |
 | Enterprise | Self-Managed, Hybrid |
 
+<Note>
+Before installing, please review our [Package and Container Image Retention Policy](/developer-support/retention-policy) to understand how we manage the lifecycle of our published container images.
+</Note>
+
 <Note>
 Running on Podman, containerd, or another container runtime? See [Container Runtimes](/deployment-and-operations/container-runtimes).
 </Note>

tyk-self-managed/install/linux.mdx

@@ -8,6 +8,10 @@ sidebarTitle: "Linux"
 | :------------- | :---------------------- |
 | Enterprise | Self-Managed, Hybrid |
 
+<Note>
+Before installing, please review our [Package and Container Image Retention Policy](/developer-support/retention-policy) to understand how we manage the lifecycle of our published packages.
+</Note>
+
 ## Compatible Operating Systems
 
 | Operating System | Version |