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] <Support --with-openssl-argon2 on Windows by cmb69 · Pull Request #15713 · php/php-src · GitHub;
Christoph
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.
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] <Support --with-openssl-argon2 on Windows by cmb69 · Pull Request #15713 · php/php-src · GitHub;
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
PHP: Migrating from PHP 8.2.x to PHP 8.3.x - Manual 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.
On 06.09.2024 at 16:38, Remi Collet wrote:
Hi,
Le 04/09/2024 à 15:04, Christoph M. Becker a écrit :
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.
There is various targets
UPGRADING is for PHP users
so only changes in the languages
UPGRADING.INTERNALS is for others
- linux builders
- windows builders
- php developers
So, I'm fine with current content.
Perhaps we could split changes about build in
separate files.
Given that the most relevant place to document such changes is
apparently controversial, this might be a good idea.
Actually, I'm fine with either solution, but I consider it *very*
important that *all* build related changes are in one place. Nobody
should be required to scan multiple documents to get this information.
And that is also important for the docs team, since they are supposed to
integrate this information into the PHP manual (first to the migration
guides, and then to the manual proper).
Christoph