Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:125432
Precedence: bulk
MIME-Version: 1.0
References: <bbe97adb-4d31-4f38-833e-f0c65c0dbcc4@gmx.de>
In-Reply-To: <bbe97adb-4d31-4f38-833e-f0c65c0dbcc4@gmx.de>
Date: Thu, 5 Sep 2024 00:33:23 +0200
Message-ID: <CAAfnsFWX=+nL5Ue-kAFFio8Eur293mK+tGK2QoONs5=o6JLP6w@mail.gmail.com>
Subject: Re: [PHP-DEV] Where to document configuration option changes?
To: "Christoph M. Becker" <cmbecker69@gmx.de>
Cc: PHP internals list <internals@lists.php.net>
Content-Type: text/plain; charset="UTF-8"
From: petk@php.net (Peter Kokot)

On Wed, 4 Sept 2024 at 15:07, Christoph M. Becker <cmbecker69@gmx.de> wrote:
>
> Hi all,
>
> that issue came up the other day on a pull request[1], but since it is
> not particularly related to any single PR, I wanted to ask here for
> clarification.
>
> This is about changes to `./configure` options of php-src, and whether
> these should be documented in UPGRADING or UPGRADING.INTERNALS.  For the
> master branch, most such changes are currently documented in
> UPGRADING.INTERNALS, but a few are in UPGRADING.
>
> In my opinion these changes should be documented in UPGRADING, but not
> in UPGRADING.INTERNALS, because they are relevant for users who build
> PHP themselves, packagers (aka distro managers) and the documentation
> team, and neither of these is supposed to read UPGRADING.INTERNALS.  And
> I believe that it has been done this way in the past.
>
> What do you think?
>
> On a general note, it might be reasonable to properly document what
> should go into UPGRADING, UPGRADING.INTERNALS and NEWS; that seems to be
> generally somewhat unclear; sometimes there are entries in NEWS *and*
> UPGRADING for the same changes, what appears to be duplicate content to me.
>
> [1] <https://github.com/php/php-src/pull/15713#issuecomment-2325981549>
>
> Christoph

I've checked some of PHP-5.x and PHP-7.x branches and it seems that
we've started adding these configure options also in
UPGRADING.INTERNALS more consistently somewhere in PHP-7.4 (probably).
Otherwise, they are noted here and there inconsistently. So far there
was no specific guideline, where to document these.

Issue here is that the person that needs to adjust their build
configuration or Linux repository package scripts, they only need to
see what configure options, need adjustments and which dependencies
need to be updated. And then the fun starts with adjusting all the
patches and everything but theoretically a single list of these types
of changes would help. Browsing the entire UPGRADING document might be
a bit confusing for this. Also, some configuration options changes are
related only to Autotools build system and some to JScript Windows
build system. Ideally, this type of page
https://www.php.net/manual/en/migration83.php would also include this
build system specifics that are needed to migrate PHP. This is in most
cases only relevant to a smaller number of people actually. PHP
developers in most cases don't build PHP from scratch.