Re: What versions should the documentation cover?

On Fri, Aug 30, 2024, 03:30 Jim Winstead <[email protected]> wrote:

> 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).
>

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.