Add deprecation policy or guide to documentation

[stevepiercy]

The Plone backend folks ported both a deprecation conceptual guide and how-to guide from earlier versions to Plone 6 in PR plone/documentation#1850.

Volto documentation lacks a deprecation policy or guide. The closest I found was Version policy, as well as the Upgrade Guide, but there's nothing in Volto documentation that sets a policy or how to deprecate in a developer-friendly way.

We could amend the main docs with Volto specific information, especially in the how-to guide. Alternatively we could add a section to the Version policy or create a new page "Deprecation policy" as a reference and "Deprecation guide" as a how-to.

I added this item to the Volto team meeting, just in case there's something more to it. It may not need discussion in a team meeting and it could be more practical to just refine this issue description.

@sneridagh @pnicolli @davisagli @wesleybl maybe you have some thoughts?

See potentially related issues containing "deprecate".

[tarunchaudharydev]

This makes sense to document clearly for Volto developers.

Would it be acceptable to start with a short "Deprecation guidelines" section
in the existing documentation, based on the Plone 6 deprecation guides,
and adapt it specifically for Volto APIs and frontend components?

Happy to help draft documentation once the preferred structure is agreed.

[bluesky-adi]

Hi @stevepiercy,

This looks like a very useful addition for Volto developers.

Before starting a PR, I wanted to clarify the preferred approach:

• Would you prefer a single “Deprecation policy” reference page for Volto,
  plus a short “How to deprecate” section with practical examples?
• Or adapting the existing Plone 6 backend deprecation guides
  with a Volto-specific section (components, hooks, APIs)?

Once the structure is agreed, I’d be happy to help draft the documentation
based on the Plone 6 deprecation guides and adapt it for Volto.

[stevepiercy]

@tarunchaudharydev and @bluesky-adi this is not a suitable issue for first-timers. See https://6.docs.plone.org/contributing/first-time.html#work-with-github-issues. It also needs to be discussed internally before any direction can be followed.

[tarunchaudharydev]

Thanks for the clarification, @stevepiercy . Understood I will pause on this and follow the contributing process.
Happy to help later if/when there’s a concrete direction or a suitable issue to work on.