Re: Removing a chapter from all translations

On Fri, 26 Jul 2024 at 02:14, Jim Winstead <[email protected]> wrote:

> Hi,
>
> I'm not sure how many translators are on this list, but I find myself
> writing the same note on a lot of the PRs I've been making to translations
> in the process of fixing https://github.com/php/doc-en/issues/3579 which
> involves removing `features/xforms.xml` which is referenced in
> `chapters/tutorial.xml`.
>
> The reference to `features.xforms` has been removed from `doc-en`. The
> `chapters/tutorial.xml` remains because it is still referenced from `
> manual.xml.in` in `doc-base` and I didn't want to break every build.
>
> I've submitted PRs to every translation to remove the chapter and the
> reference to it. I'm going back and updating the PRs to update the revision
> tags on `chapters/tutorial.xml`. (Sorry, I hadn't caught up to that part of
> how the translations are managed. Very nice!)
>
> As the translations merge those PRs, that means they'll get built with the
> English version of that chapter. But once it has been removed from all
> translations, I'll go ahead and remove it from `manual.xml.in` and the
> `doc-en` repository, the entities in `doc-base` that only appear in that
> chapter, and it will finally be gone.
>
> The other reason I'm writing this for this list is to sort of document the
> process of removing a chapter from the manual while not causing any build
> failures:
>
> 1. Remove any references to it from `doc-en`.
> 2. Remove those references and the chapter itself from the translations.
> (Update the EN revision on updated files.)
> 3. Remove reference to it from `doc-base`.
> 4. Remove it from `doc-en`.
> 5. If there are any entities used only in that chapter, remove them from
> `doc-base`.
>
> Step 2 will be be more complicated if the references aren't a standalone
> paragraph like this case was, where it was easy to just the reference
> without having to actually understand any of the translations.
>
> Jim
>

The correct thing to do is to break the build for translations.
You can have PRs and patches ready to apply onto the affected translations,
but applying them first and then needing to go back to update the revcheck
is confusing.
The one exception is if you are removing a file from doc-en, in which case
pre-empting the removal in translations is okay.

Best,

Gina P. Banyard