Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document how to contribute deprecations #482

Merged
merged 1 commit into from
May 30, 2023
Merged

Document how to contribute deprecations #482

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 3 additions & 1 deletion source/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
29 changes: 29 additions & 0 deletions source/policies/deprecation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,15 @@ 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.
When deprecating something an API in favor of another API, the new API
must be already present or added in the same minor version as the
deprecation.

Using ``@deprecated`` and ``PHPStan Deprecation Rules``
-------------------------------------------------------

Expand Down Expand Up @@ -61,6 +70,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
-----
Expand Down