Re: Removing a chapter from all translations

On Fri, 26 Jul 2024 at 02:14, Jim Winstead <jimw@trainedmonkey.com> 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