Review main Merged

83393[DOCS] Rename .rst includes to .rst.txt

Lina Wolf CR +2 V +2 Expert +1147 −1147 updated 03/09/24, 18:19

Commit message

All files ending on .rst are interpreted as documents in both the new and old rendering. This leads to warnings and errors. So all files to be included are renamend to .rst.txt as is standard.

Additionally include files should not include the Includes.rst.txt as it is already included in the main file. Those includes are removed.

Review

  • Code review CR +2 Done
    • Lina Wolf +2
    • Garvin Hicking +1
  • Verified V +2 Done
    • Lina Wolf +2
    • Garvin Hicking +1
    • core-ci +1 CI

Issues 1

Files 936

Show 916 more files

Review log 1318

  1. Lina Wolf uploaded patch set 1 03/09/24, 11:33

  2. Lina Wolf updated the commit message in patch set 2 03/09/24, 11:36

  3. Lina Wolf uploaded patch set 3 03/09/24, 11:37

  4. Lina Wolf updated the commit message in patch set 4 03/09/24, 11:38

  5. core-ci voted on patch set 2 V +1 03/09/24, 11:42 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/54321

  6. core-ci voted on patch set 1 V -1 03/09/24, 11:42 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/54320

  7. core-ci voted on patch set 3 V +1 03/09/24, 11:43 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/54322

  8. core-ci voted on patch set 1 V +1 03/09/24, 11:46 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/54320

  9. core-ci voted on patch set 4 V +1 03/09/24, 11:46 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/54323

  10. Benjamin Franzke commented on patch set 4 CR -1 03/09/24, 15:35

    Such renames are unfortunate for `git blame`. Any chance the issue (which I unfortunately can not understand from the commit message or issue descrption) can be resolved without renaming all .rst files? Is this issue only popping up as long as both old renderer and new one are used in parallel? If that is the case, then please switch all to the new one and avoid this change.
  11. Lina Wolf commented on patch set 4 03/09/24, 15:44

    Reply

    Unfortunate the files should have never been uploaded like this. Each file that is supposed to be included in other files is treated - in both the old and new rendering - like it would be a standalone document. It causes tons of warnings and document stubs that are rendered an published (duplicate content) even though they are not needed. HTML files like https://docs.typo3.org/c/typo3/cms-form/main/en-us/D/FrontendRendering/AbstractRenderable/setLabel.html and https://docs.typo3.org/c/typo3/cms-form/main/en-us/I/Config/proto/formElements/formElementTypes/Date/formEditor/propertyCollections/validators/10/editors/100.html are genererated in the hundrets. For that reason it is also strictly against the coding guidelines to import .rst files. The only reason I can see why this was ever merged is that no one looked at or cared about the error log or the files that are generated and published. So I believe a clean up is very important and less losing git-blame opportunities is less harmful.
  12. Nikita Hovratov commented on patch set 4 03/09/24, 16:03

    Reply

    @ben@bnf.dev Why is this unfortunate for git blame? I mean the history is perfectly preserved, as git only tracks the content, not the file. I know that I don't tell you anything new, so maybe you could enlighten me? Anyway, I would let the documentation experts just do their thing. This is their domain, we should not block their work.
  13. Benjamin Franzke commented on patch set 4 CR 0 03/09/24, 17:03

    Reply

    @112@linawolf.de Thanks for the explanation. @nikita.h@live.de I mixed things up. The issue I remembered was not related to `git blame`, but `git log` on a specific file (which often is more useful than git-blame when trying to find commits that changed a file in a given range). Anyway, this is fine be my, as I've now understood the technical reason.
  14. Benjamin Franzke commented on patch set 4 03/09/24, 17:52

    Reply

    Just for reference: This is the `git blame` issue I referred to: https://stackoverflow.com/questions/29468273/why-git-blame-does-not-follow-renames (recursive git-blame becomes harder as you have to change filenames of the CLI command, whenever you encounter a unrelated change in `git blame` and need to look back further). For sure, we got a ton of those cases already and that's not blocking this change, but I asked for alternatives, as I – being absolutely naive – thought the doc-renderer looks at defined entry point filenames instead of processing all files as entry points.
  15. Lina Wolf commented on patch set 4 03/09/24, 17:57

    Reply

    Oh, we do have a defined entrypoint (Documentation/Index.rst), however Documents not in the document tree also get rendered and can be linked to and a document is defined by having a .rst or .md file within the dedicated paths.
  16. Garvin Hicking commented on patch set 4 CR +1 V +1 03/09/24, 18:19

    Thanks for talking this over. Sadly I also don't see an alternative to this mass-rename ;'(
  17. Lina Wolf voted on patch set 4 CR +2 V +2 03/09/24, 18:19

  18. Lina Wolf merged patch set 5 03/09/24, 18:19