Deprecation guide

[soapy1]

Description

This PR adds some docs around how conda-store is handling deprecations. It also adds a Sunset header to deprecated api endpoints to denote when they will be removed.

[netlify]

✅ Deploy Preview for conda-store ready!

Name	Link
🔨 Latest commit	9afaf5c
🔍 Latest deploy log	https://app.netlify.com/sites/conda-store/deploys/677d750a601fc60008b518d2
😎 Deploy Preview	https://deploy-preview-1018--conda-store.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[trallard]

Thanks for working on this @soapy1, though this overlaps with our existing policies so added a few comments that will need to be adressed

[trallard]

See comment above:

The removal date can be set to (at earliest) the date of the target
next release.

Since we use CalVer and do not have set release dates, this puts us in a position where we need to agree on a release and meet it no matter what.
Since we do not have a set release schedule, this is rather ambiguous, so we need a clearer guideline here.

[soapy1]

I can be more specific here.

I think sunset date should be set to about 2 months from the release that the deprecation is going out in.

• Any time before this date, users should expect this endpoint to work
• Any time after this date, the endpoint may still be available (due to no release having gone out), but users should expect that this endpoint will disappear

For example, say you have an endpoint /hello-planet that is getting deprecated. The whole removal cycle will be something like:

• 2024/12/17 - add deprecation headers to /hello-planet, sunset date is 2025/03/17
• 2024/12/19 - new release goes out (sunset date is more than 2 months away, so everything is good)
• 2025/01/30 - new release goes out, /hello-planet is still deprecated
• 2025/03/16 - new emergency release goes out to fix a discovered security vulnerability. Still before the /hello-planet sunset date, so it remains in the deprecated state
• 2025/03/17 - /hello-planet sunset date. No release so this endpoint is still functional, however will be yanked at next release
• 2025/03/29 - new release goes out /hello-planet endpoint functionality is removed, returns a 410 response with removal date (eg. 2025/04/29)
• 2025/04/29 - new release goes out. Happens to coincide with the removal date. Can remove the endpoint as part of this release

[soapy1]

I don't think the removal of functionality step offers much more help to users than the deprecation step. If the team is open to changing this more, I would advocate for jumping straight from deprecating the endpoint to removing the endpoint after the sunset date.