Where to document configuration option changes? View as Markdown

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?

I agree with you, that ./configure option changes should ideally be
listed in the UPGRADING file.

For packagers, I would imagine they now have to lookup both UPGRADING
(INI changes, underlying libraries such as libcurl-dev minimum version
bumps, alternative PCRE2 versions, etc) as well as the
UPGRADING.INTERNALS for ./configure flags. Apart from the "Build
system changes" section, the rest of the UPGRADING.INTERNALS file is
only useful when developing PHP extensions or php-src itself.

If we were to move the Build System Changes to the UPGRADING file, all
"user" and "packager" facing changes are listed in the UPGRADING file,
Change log in the NEWS file, and PECL/php-src related changes in the
UPGRADING.INTERNALS file.

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.