Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:107937
To: Peter Cowburn <petercowburn@gmail.com>,
 Rowan Tommins <rowan.collins@gmail.com>
Cc: PHP internals <internals@lists.php.net>
References: <CAH5C8xXnubQv-7CoAR=vjH1qXCmy6omF-8qQktd+QGFvAwQL0Q@mail.gmail.com>
 <bbd5b8c4-31a7-2266-0339-1b2c3a6adbed@gmx.de>
 <CALKiJKpKFbY1n2bvZdwAQ_dX-p7nm20CJ8yvVxO_eVzJUabF5g@mail.gmail.com>
 <CAPg3XxJFZQgaZ7=zB9a21TM1ZwTXF+fvs6NUOyhMGwHn8S6ToA@mail.gmail.com>
Message-ID: <1ba63ecf-5fe2-bb6b-afa8-655bfca45097@gmx.de>
Date: Fri, 20 Dec 2019 14:09:24 +0100
User-Agent: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:60.0) Gecko/20100101
 Thunderbird/60.9.1
MIME-Version: 1.0
In-Reply-To: <CAPg3XxJFZQgaZ7=zB9a21TM1ZwTXF+fvs6NUOyhMGwHn8S6ToA@mail.gmail.com>
Content-Type: text/plain; charset=utf-8
Content-Language: de-DE
Content-Transfer-Encoding: quoted-printable
Subject: Re: [PHP-DEV] Re: Changelog / upgrading notes for promoted warnings
From: cmbecker69@gmx.de ("Christoph M. Becker")

On 20.12.2019 at 10:39, Peter Cowburn wrote:

> On Fri, 20 Dec 2019 at 09:31, Rowan Tommins <rowan.collins@gmail.com> wr=
ote:
>
>> On Fri, 20 Dec 2019 at 08:37, Christoph M. Becker <cmbecker69@gmx.de>
>> wrote:
>>
>>> Maybe a sensible compromise would be to assemble a detailed list of
>>> these changes, and to hand it over to the doc team at some point, so
>>> that the manual pages could (hopefully) be updated in time just before
>>> PHP 8.0.0 will be released.  Then users could check the manual's
>>> changelog[1] regarding the details.
>>
>> Yes, that sounds reasonable. In many cases, the individual function lis=
ting
>> should also have a note added at the same time; and at some future date=
,
>> some will be able to lose their "may return false" notes.
>
> This is usually where the UPGRADING document comes in to play. While
> watching all of the PRs against master I've very much not been looking
> forward
> to making sense of all of changes when it comes to updating the PHP manu=
al
> to
> reflect them.

Then I would like to suggest a separate section in UPGRADING for these
"mass" changes, where we can note that arguments of wrong type now throw
a TypeError (instead of raising E_WARNING before), and that also some
further argument checks will have been elevated from E_WARNING to Error,
followed by a detailed list.  For instance, for ext/calendar:

- Calendar:
  . cal_info(), cal_days_in_month(), cal_to_jd() and cal_from_jd() now
    throw ValueError if an invalid calendar ID is given
  . cal_days_in_month() now throws ValueError if an invalid date is
    given
  . jdtojewish() now throws ValueError if the given year is out of range

Thoughts?

=2D-
Christoph M. Becker