Document how to contribute deprecations

doctrine · May 30, 2023 · 9cfa352 · 9cfa352
1 parent a009d28
commit 9cfa352
Show file tree

Hide file tree

Showing 2 changed files with 29 additions and 1 deletion.
diff --git a/source/contribute.rst b/source/contribute.rst
@@ -129,7 +129,9 @@ The next minor version branch may include:
 
 - refactorings, unless they are necessary for a bugfix. This is to avoid
   unnecessary risks.
-- new deprecations - remember to update the ``UPGRADE.md`` file as well!
+- new deprecations - read our :ref:`Dedicated policy
+  <./policies/deprecation>` to figure out
+  how to contribute those.
 - adding new features and/or public APIs;
 
 On the next major version branch, usually only deprecations notices,

diff --git a/source/policies/deprecation.rst b/source/policies/deprecation.rst
@@ -3,6 +3,12 @@ Deprecation Policy
 
 The Doctrine team will adhere to this deprecation policy whenever it is reasonably possible.
 
+When to deprecate something
+---------------------------
+
+Deprecations can only ever happen in a minor release. Users pulling a
+patch version of the library should not get a new deprecation.
+
 Using ``@deprecated`` and ``PHPStan Deprecation Rules``
 -------------------------------------------------------
 
@@ -61,6 +67,26 @@ Using ``doctrine/deprecations``
 In some cases, you may need to conditionally deprecate functionality. In
 these cases, it is required to use the `Doctrine deprecations`_ library.
 
+Documenting the deprecation
+---------------------------
+
+Any pull request labeled with "Deprecation" must include a change in
+``UPGRADE.md`` documenting what is deprecated, and how to migrate to the
+new API if any. When using ``doctrine/deprecations``, a link is required
+as an argument to ``Deprecation::trigger*()``. That link can be a link
+to the pull request if it explains the deprecation clearly in its
+description, or a link to a separate issue. It should explain why there
+is a deprecation.
+
+Cleaning up deprecations
+------------------------
+
+Once a deprecation has been merged, and the next minor version has been
+merged up into the next major version, the deprecation can and should be
+removed from the next major branch.
+This is best done by the person who contributed the deprecation.
+It involves removing the deprecated paths, but also contributing another
+entry in ``UPGRADE.md`` stating what has been removed.
 
 Tools
 -----