Re: What versions should the documentation cover?

On Sun, Aug 25, 2024, at 12:23 PM, Christoph M. Becker wrote:
> On 25.08.2024 at 20:37, Jim Winstead wrote:
>
>> Gina suggested (https://github.com/php/doc-base/pull/146#issuecomment-2308900139
>> <https://github.com/php/doc-base/pull/146#issuecomment-2308900139>) that we
>> should remove older function changelog entries from the documentation rather
>> than just configure the page generated to exclude old versions.
>>
>> 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 <https://www.php.net/docs.php>, 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.
>
> [1] <https://news-web.php.net/php.doc/969387407> ff
> [2] <https://news-web.php.net/php.doc/969387511> ff

I submitted a PR to add a paragraph to the preface about what versions are documented in the manual.

https://github.com/php/doc-en/pull/3700

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.

Jim