Re: Maintaining PHP 5 documentation

On Fri, 4 Dec 2020 at 21:57, Giovanni Giacobbi <[email protected]>
wrote:

> On Fri, Dec 4, 2020, 21:03 Christoph M. Becker <[email protected]> wrote:
>
>> On 04.12.2020 at 20:17, Gabriel Caruso wrote:
>>
>> > On Fri, Dec 4, 2020, 16:14 Gabriel Caruso <[email protected]>
>> wrote:
>> >
>> >> On Fri, Dec 4, 2020, 16:01 Anna Filina <[email protected]> wrote:
>> >>
>> >>> I landed on this plain 404 page yesterday:
>> >>> https://www.php.net/manual/en/ini.sect.safe-mode.php#ini.safe-mode
>> >>>
>> >>> I was told that the PHP 5 docs are in the process of being removed
>> from
>> >>> php.net. This is not ideal for me as I maintain and migrate legacy
>> >>> applications for a living.
>> >>>
>> >>> I would like to understand the reasoning behind this decision and
>> perhaps
>> >>> offer some help to remedy the situation:
>> >>> - Are there any inherent problems with keeping the legacy docs online?
>> >>> - How much effort does it require to maintain the legacy docs?
>> >>> - Are there any associated costs?
>> >>
>> >> I believe this was the PR archiving it:
>> >> https://github.com/php/web-php/pull/341
>> >>
>> >> I'll check in the mailing list of there's a discussion thread
>> meanwhile.
>> >
>> > There you go: https://news-web.php.net/php.doc/969387511
>>
>> That message referred to another thread, which is
>> <https://marc.info/?l=phpdoc&m=157659936427907&w=2>.
>>
>> The basic problem with maintaining documentation for PHP 5 is the
>> overhead for maintainers (who are not as numerous as the stars in the
>> sky; actually it's more like the number of planets you can see in the
>> sky with the naked eye), *and* for most readers (there are sometimes
>> long changelog lists, and some notes sprinkled through the text
>> regarding behavior as of, or prior to certain PHP versions).
>
>
> I'm also maintaining some legacy PHP 5.x code and am very upset about this
> change. I would not expect anyone to do extra maintenance work, but it
> would be very kind if you could republish the old docs as
> legacy-docs.php.net or something? It's very handy sometimes to see which
> methods and parameters were available in a certain version to know if you
> can use them or not. I know it would still be some work to maintain a
> separate docs http installation but i think that's a very reasonable
> effort? If I can help, I would.
>

Other than the usual troll comment that one can make about needing to
migrate
away from PHP 5 as PHP 7.0 got release 5 years and a day ago, we still
received
numerous bug reports about undocumented behaviour specific to PHP 5 that we
needed to go and add as the official docs need to be as complete as
possible.

Moreover, there is no PHP 5.X version which is officially maintained by the
PHP
project anymore, thus why should the project bother maintaining
documentation
for it?
If we are going to set up legacy docs, should we also put up online docs for
PHP 4, what about PHP 3?

Prior to Peter Cowburn's retirement from Doc Editor there were discussions
about
removing pre-PHP 5.4 docs to make it easier to maintain, but it was decided
against
and that the whole of PHP 5 docs should be removed when PHP 8 get
released/documented on the manual as, from my understanding, only the
latest 2
major versions should be actively documented.

As a reminder the PHP documentation is released under the Creative Commons
Attribution 3.0 licence [1] and the tools made to build it are also open
source.
So anyone can just republish the archive online or fork the SVN/git repo
from the
commit prior to its removal and publish it online at some other address.

So if someone wants to take ownership of that project they are free to do
it and
we can possibly sort out some way to link to it from the official docs with
a
disclaimer that doc bugs about the legacy docs should be redirect to that
specific team.

Best regards,

George P. Banyard

[1] https://www.php.net/manual/en/cc.license.php