I agree, and I poked around a little to see if there was any policy/guidance about what versions the documentation is meant to cover. If there is, I didn’t find it.
It’s tempting to say we should just be documenting the supported versions, but I think migration from old versions is a key usage for the manual so it makes sense to have a longer timeline.
Here’s what I would propose:
The documentation is intended to cover the current and previous major version of PHP (as of now, PHP 7 and 8).
Migration guides from earlier versions should continue to be included.
Extension version information should continue to cover all versions.
Am I missing anything from this? This would mean that functions or extensions that only exist in versions prior to PHP 7 could now be excised from the documentation, as well as those older function changelog entries.
I’d like to add a section to the preface that captures this (or whatever else we decide). Alternatively, we could create a whole appendix that pulls in all of the ‘PHP Manual Contribution Guide’ stuff from doc.php.net.
I agree, and I poked around a little to see if there was any policy/guidance about what versions the documentation is meant to cover. If there is, I didn’t find it.
It’s tempting to say we should just be documenting the supported versions, but I think migration from old versions is a key usage for the manual so it makes sense to have a longer timeline.
Here’s what I would propose:
The documentation is intended to cover the current and previous major version of PHP (as of now, PHP 7 and 8).
Migration guides from earlier versions should continue to be included.
Extension version information should continue to cover all versions.
Am I missing anything from this? This would mean that functions or extensions that only exist in versions prior to PHP 7 could now be excised from the documentation, as well as those older function changelog entries.
I’d like to add a section to the preface that captures this (or whatever else we decide). Alternatively, we could create a whole appendix that pulls in all of the ‘PHP Manual Contribution Guide’ stuff from doc.php.net.
I agree, and I poked around a little to see if there was any policy/guidance
about what versions the documentation is meant to cover. If there is, I didn’t
find it.
It’s tempting to say we should just be documenting the supported versions, but I
think migration from old versions is a key usage for the manual so it makes
sense to have a longer timeline.
Here’s what I would propose:
* The documentation is intended to cover the current and previous major version
of PHP (as of now, PHP 7 and 8).
* Migration guides from earlier versions should continue to be included.
* Extension version information should continue to cover all versions.
Am I missing anything from this? This would mean that functions or extensions
that only exist in versions prior to PHP 7 could now be excised from the
documentation, as well as those older function changelog entries.
I’d like to add a section to the preface that captures this (or whatever else we
decide). Alternatively, we could create a whole appendix that pulls in all of
the ‘PHP Manual Contribution Guide’ stuff from doc.php.net.
See <PHP: Manual Quick Reference, last item. That PHP4 and PHP5 doc
removal happened a couple of years ago (after discussion on the
list[1][2]), though some remnants about these old versions can still be
found in the docs, and these can (and should) be removed.
Back then we decided to also remove the old migration guides but chose
to keep migration56 and migration70 as service for the community. Maybe
these should be removed now as well.
I agree, and I poked around a little to see if there was any policy/guidance
about what versions the documentation is meant to cover. If there is, I didn’t
find it.
It’s tempting to say we should just be documenting the supported versions, but I
think migration from old versions is a key usage for the manual so it makes
sense to have a longer timeline.
Here’s what I would propose:
* The documentation is intended to cover the current and previous major version
of PHP (as of now, PHP 7 and 8).
* Migration guides from earlier versions should continue to be included.
* Extension version information should continue to cover all versions.
Am I missing anything from this? This would mean that functions or extensions
that only exist in versions prior to PHP 7 could now be excised from the
documentation, as well as those older function changelog entries.
I’d like to add a section to the preface that captures this (or whatever else we
decide). Alternatively, we could create a whole appendix that pulls in all of
the ‘PHP Manual Contribution Guide’ stuff from doc.php.net.
See <PHP: Manual Quick Reference, last item. That PHP4 and PHP5 doc
removal happened a couple of years ago (after discussion on the
list[1][2]), though some remnants about these old versions can still be
found in the docs, and these can (and should) be removed.
Back then we decided to also remove the old migration guides but chose
to keep migration56 and migration70 as service for the community. Maybe
these should be removed now as well.
Before anything destructive gets done, I think we should create an archive (and host it) so that people who unfortunately still need this (due to having to upgrade really old stuff), aren't shafted.
See <PHP: Manual Quick Reference, last item. That PHP4 and PHP5 doc
removal happened a couple of years ago (after discussion on the
list[1][2]), though some remnants about these old versions can still be
found in the docs, and these can (and should) be removed.
Back then we decided to also remove the old migration guides but chose
to keep migration56 and migration70 as service for the community. Maybe
these should be removed now as well.
Before anything destructive gets done, I think we should create an archive (and host it) so that people who unfortunately still need this (due to having to upgrade really old stuff), aren't shafted.
Some time, read the old documentation is needed to work on oldest applications.
Make an archive is a good idea but the archive will must be accessible easily from the documentation.
Best regards,
Jean-Baptiste
Win32service Lead Dev
French PHP documentation translator
Le 25 août 2024 à 21:52, Christoph M. Becker <cmbecker69@gmx.de> a écrit :
On 25.08.2024 at 21:35, Derick Rethans wrote:
See <PHP: Manual Quick Reference, last item. That PHP4 and PHP5 doc
removal happened a couple of years ago (after discussion on the
list[1][2]), though some remnants about these old versions can still be
found in the docs, and these can (and should) be removed.
Back then we decided to also remove the old migration guides but chose
to keep migration56 and migration70 as service for the community. Maybe
these should be removed now as well.
Before anything destructive gets done, I think we should create an archive (and host it) so that people who unfortunately still need this (due to having to upgrade really old stuff), aren't shafted.
I agree, and I poked around a little to see if there was any policy/guidance
about what versions the documentation is meant to cover. If there is, I didn’t
find it.
It’s tempting to say we should just be documenting the supported versions, but I
think migration from old versions is a key usage for the manual so it makes
sense to have a longer timeline.
Here’s what I would propose:
* The documentation is intended to cover the current and previous major version
of PHP (as of now, PHP 7 and 8).
* Migration guides from earlier versions should continue to be included.
* Extension version information should continue to cover all versions.
Am I missing anything from this? This would mean that functions or extensions
that only exist in versions prior to PHP 7 could now be excised from the
documentation, as well as those older function changelog entries.
I’d like to add a section to the preface that captures this (or whatever else we
decide). Alternatively, we could create a whole appendix that pulls in all of
the ‘PHP Manual Contribution Guide’ stuff from doc.php.net.
See <PHP: Manual Quick Reference, last item. That PHP4 and PHP5 doc
removal happened a couple of years ago (after discussion on the
list[1][2]), though some remnants about these old versions can still be
found in the docs, and these can (and should) be removed.
Back then we decided to also remove the old migration guides but chose
to keep migration56 and migration70 as service for the community. Maybe
these should be removed now as well.
I submitted a PR to add a paragraph to the preface about what versions are documented in the manual.
Like I said, I think leaving the migration guides in is fine, I think the things to cut out would be extensions that are no longer included and old changelog entries. There's probably not much of that in the manual now, really.
This will spawn a bigger clean-up when PHP 9.0 comes out, though. Reading those old threads, I hope that might be less controversial because the core is on a more regular release schedule now.
I agree, and I poked around a little to see if there was any policy/guidance
about what versions the documentation is meant to cover. If there is, I didn’t
find it.
It’s tempting to say we should just be documenting the supported versions, but I
think migration from old versions is a key usage for the manual so it makes
sense to have a longer timeline.
Here’s what I would propose:
The documentation is intended to cover the current and previous major version
of PHP (as of now, PHP 7 and 8).
I disagree on the “two major versions” policy. it should rather be explicitly “starting from php7”. Although the version history was sadly dropped for php5, i believe the php7 history should be kept even when php9 happens. People might want to write apps compatible with all versions, so functions changelog is very useful. I believe php7 will be around for a while more.
Once php7 docs become undoubtly useless, this can be revised. I have the gut feeling that php7 will live much longer than php8, meaning that who is already on 8 will switch to 9, and who is in 7 will stay on 7 or switch directly to 9. For sure that’s what i’ll do.