Scan doc-contrib directory in file-entities generation

[lacatoire]

Counterpart to the new lacatoire/doc-contrib repository, implementing the accepted RFC on separation of third-party extension documentation.

When a doc-contrib/ directory exists alongside en/ in the root, file-entities.php now scans it before doc-en/. Entities from doc-en override doc-contrib where both repositories define the same file, so migration is incremental: removing an extension from doc-en is sufficient to hand it off to doc-contrib.

The RFC covers a large set of extensions. php/doc-en#5665 tracks the first wave of candidates (seven long-unmaintained PECL extensions) to validate the handoff mechanism before broader migration.

[alfsb]

The PR is ok as is. Next are some comments and considerations.

• I'm coming very late in this discussion, but I suggest doc-vendor or doc-external, instead of doc-contrib, to better describe the nature of what is documented here.

"contrib" seems to me as something there is deposited into or from elsewhere, while vendor/external rings a little more as "third-party", at least for me (English is not my first language, though).

• No translation is possible, all translations will be lost.

Including files from directories (or repositories) outside doc-en mean these files will never show in revchecks, so translators will not be prompted to translate these.

Worse, as these files are finally "moved", they will show as "only en EN files", an indication these files should be deleted from translations (semi-correctly, btw, because the "same" files may show both in English and translated, in all translations, as paths start diverging).

Also, doc-contrib is really doc-contrib-en, as it has reference/ directly at root. I see no discussion of translations in the RFC, so this is also a "too late" aspect to consider. Renaming it do docvendor-en, or slight worse (but something that may need to be done anyways) to create a en/´directory on root, so translations can be moved there... and then, "text" entities and revcheck machinery will also need some updates like these.

One repo per language vs one repo for all languages has write access implications to consider.

• Again, ok to merge

As voted on by the RFC, this change is ok.

[lacatoire]

You're right about the translation machinery, it's a real limitation. For now, the extensions targeted here are abandoned/unmaintained, so there's no active translation community to break. It's also a way to get familiar with the overall workflow before tackling more complex cases. The translation architecture concern is worth addressing in a follow-up once the first batch is in.
BTW i quite liked doc-ext, short and effective but the RFC referred to doc-contribute.

[alfsb]

Now, something that I am a little confused about. There are two "third-party" projects in the works?

One for third-party extensions, to be moved outside of language manual, and another for third-party projects, hosted outside the PHP project infra-estrucuture, but to be included in the PHP Manual?

I remember reading about the splitting of third-party extensions in the language manual, but the link above does not mention any splitting, only the fear of endorsing.

[alfsb]

You're right about the translation machinery, it's a real limitation. For now, the extensions targeted here are abandoned/unmaintained, so there's no active translation community to break.

But there quite a few translation communities that keep translations at the perfect 100% on revcheck, that will be upset. These need at least a heads up.

It's also a way to get familiar with the overall workflow before tackling more complex cases. The translation architecture concern is worth addressing in a follow-up once the first batch is in. BTW i quite liked doc-ext, short and effective but the RFC referred to doc-contribute.

Name or direct link for the RFC? To see if there are other impacts to consider.

But it is still a good time to open a new RFC, only to rename the repository, and/or to rename folders inside it to add lang/ folders.

[lacatoire]

RFC: https://wiki.php.net/rfc/third-party_code The lang/ folder question is a good one, even a separate RFC.

[alfsb]

RFC: https://wiki.php.net/rfc/third-party_code The lang/ folder question is a good one, even a separate RFC.

"This topic does not exist yet"

There is tree "third" RFCs

• 2024-08-24 https://wiki.php.net/rfc/web-and-doc-use-not-endorsement
• 2024-10-02 https://wiki.php.net/rfc/third-party-code
• 2026-05-27 https://wiki.php.net/rfc/third_party_ext_documentation

What confused me is that only the last one talks about manual splitting. Now I understand we are talking about "splitting" (more than "mentioning/endorsing").

In this case, the full split from the start is the way to go. There are still a few things to change on doc-base (and doc-en), but these need to be tackled sooner than later. I will try to work on these in the next days/weeks.

This PR can be merged in the meantime, if it helps on what you are doing, and I will merge it by Thursday if no one opposes.

[alfsb]

Deleted a duplicated comment of mine, above.

On further consideration, I do not think that including files from outside of doc-en into doc-en is really a hand off, as the final objective is having two complete separate manuals.

If the inclusion or removal of an extension in the main manual breaks it, it needs to be fixed only here. Also, if the inclusion or removal of an extension in the extension manual breaks there, then the fixing needs to be done only there. No mutual breakage should be ever observed.

What the file inclusion of doc-contrib into doc-en really does is creating a cross repository dependence, that will make the "final" split much harder, than starting anew, with few files / small extensions.