On Fri, Apr 26, 2024 at 11:01 AM Benjamin Außenhofer <kont...@beberlei.de> wrote:
> After discussing with Mate shortly one reason for adding $since from a PHP > project POV is that we do show the $since information in the generated > documentation output. > > Integrating with the work in progress to auto generate parts of the > function docs based on the stub files, having the $since attribute on the > stubs would allow to use this as the central information in code. Therefore > we would reconsider and add the $since argument to the Deprecated class. > > I am still partly on the side on Rowan ( > https://externals.io/message/123184#123206) that i don't find the > arguments for this parameter very convincing but at least there is a > use-case internally now that warrants adding it. > Hey. Before including the `since` parameter, please consider this: Let's assume the usual (or at least, the most common) development flow includes creating a separate branch where development happens before it's merged into the default branch. With that in mind, let's go through the flow: - tag 2.1.1 exists at some ref - the `master` branch is ahead of tag `2.1.1` and contains some unreleased, untagged changes - a new branch `deprecate-something` is created from `master` - a function is deprecated with the attribute: `#[Deprecated(since: '2.1.1')]` - a pull request is created from `deprecate-something` into `master`, but isn't merged yet - a new version is tagged and released - either `2.1.2`, `2.2.0` or `3.0.0` At this point `deprecate-something` contains an incorrectly specified `since: '2.1.1'` which needs to be updated by hand, or require additional tooling on top to update it automatically. Updating it by hand is tedious and may be needed to be done multiple times before the PR is merged. It's also not error-prone, as you may make a typo or just forget about the deprecation. This is also why Composer parses package version from the Git tags and advocates against specifying it manually: https://getcomposer.org/doc/04-schema.md#version
