Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:123218
Precedence: bulk
MIME-Version: 1.0
References: <CAEPJdumvJNQ+JZ3wkLP-Q2O0y57g=W_hHFkuvOKMVJqqraKCzw@mail.gmail.com>
 <CAAKU0uk6UYs_0sJr28gkmN_iwPcaF=z9Cr=dqOLTMHji7UNxHg@mail.gmail.com> <CAEPJdu=o06TSMC+TdR09=JYO_Hni2yQxMLeBA3s6nuZfy21POg@mail.gmail.com>
In-Reply-To: <CAEPJdu=o06TSMC+TdR09=JYO_Hni2yQxMLeBA3s6nuZfy21POg@mail.gmail.com>
Reply-To: autaut03@gmail.com
Date: Fri, 26 Apr 2024 16:38:38 +0300
Message-ID: <CABigaAWehrKf8SNespFkvQ3jG4NOvcK3AtZj3G07_kZ8wo36bA@mail.gmail.com>
Subject: Re: [PHP-DEV] [RFC] [Discussion] #[\Deprecated] attribute again v1.3
To: =?UTF-8?Q?Benjamin_Au=C3=9Fenhofer?= <kontakt@beberlei.de>
Cc: Levi Morrison <levi.morrison@datadoghq.com>, PHP Internals <internals@lists.php.net>, 
	"tim@tideways-gmbh.com" <tim@tideways-gmbh.com>
Content-Type: multipart/alternative; boundary="00000000000014b2910617000627"
From: autaut03@gmail.com (Alex Wells)

--00000000000014b2910617000627
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Fri, Apr 26, 2024 at 11:01=E2=80=AFAM Benjamin Au=C3=9Fenhofer <kontakt@=
beberlei.de>
wrote:

> After discussing with Mate shortly one reason for adding $since from a PH=
P
> 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. Therefo=
re
> 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

--00000000000014b2910617000627
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr">On Fri, Apr 26, 2024 at 11:01=E2=80=AFAM =
Benjamin Au=C3=9Fenhofer &lt;<a href=3D"mailto:kontakt@beberlei.de">kontakt=
@beberlei.de</a>&gt; wrote:<br></div><div class=3D"gmail_quote"><blockquote=
 class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px so=
lid rgb(204,204,204);padding-left:1ex"><div dir=3D"ltr"><div class=3D"gmail=
_quote"><div>After discussing with Mate shortly one reason for adding $sinc=
e from a PHP project POV is that we do show the $since information in the g=
enerated documentation output.</div><div><br></div><div>Integrating with th=
e 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 th=
is as the central information in code. Therefore we would reconsider and ad=
d the $since argument to the Deprecated class.</div><div><br></div><div>I a=
m still partly on the side on Rowan (<a href=3D"https://externals.io/messag=
e/123184#123206" target=3D"_blank">https://externals.io/message/123184#1232=
06</a>) that i don&#39;t find the arguments for this parameter very convinc=
ing but at least there is a use-case internally now that warrants adding it=
.</div></div></div></blockquote><div><br></div><div>Hey. Before including t=
he `since` parameter, please consider this:</div><div><br></div><div>Let=
9;s assume the usual (or at least, the most common) development flow includ=
es creating a separate branch where development happens before it&#39;s mer=
ged into the default branch. With that in mind, let&#39;s go through the fl=
ow:</div><div><br>=C2=A0 - tag 2.1.1 exists at some ref</div><div>=C2=A0 - =
the `master` branch is ahead of tag `2.1.1` and contains some unreleased, u=
ntagged changes</div><div>=C2=A0 - a new branch `deprecate-something` is cr=
eated from `master`</div><div>=C2=A0 - a function is deprecated with the at=
tribute: `#[Deprecated(since: &#39;2.1.1&#39;)]`</div><div>=C2=A0 - a pull =
request is created from `deprecate-something` into `master`, but isn&#39;t =
merged yet</div><div>=C2=A0 - a new version is tagged and released - either=
 `2.1.2`, `2.2.0` or `3.0.0`</div><div><br>At this point `deprecate-somethi=
ng` contains an incorrectly specified `since: &#39;2.1.1&#39;` which needs =
to be updated by hand, or require additional tooling on top to update it au=
tomatically.<br><br>Updating it by hand is tedious and may be needed to be =
done multiple times before the PR is merged. It&#39;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:=C2=A0<a href=3D"https://getcomposer.org/doc/04-sch=
ema.md#version">https://getcomposer.org/doc/04-schema.md#version</a></div><=
/div></div>

--00000000000014b2910617000627--