On Wed, 4 Sept 2024 at 15:07, Christoph M. Becker <cmbecke...@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.
