Review main Merged

85590[DOCS] Document site sets of EXT:fluid_styled_content

Lina Wolf CR +2 V +2 Hard +234 −26 updated 08/27/24, 08:06

Commit message

This patch adds a description on how to utilize
site sets from `EXT:fluid_styled_content` and the
supported configuration directives, autogenerated from
the settings.definitions.yaml file.

Review

  • Code review CR +2 Done
    • Garvin Hicking +2
    • Chris Müller +1
    • Benjamin Franzke +1
  • Verified V +2 Done
    • Garvin Hicking +2
    • Chris Müller +1
    • Benjamin Franzke +1
    • core-ci +1 CI

Issues 1

Files 14

Review log 3243

Show 1218 earlier messages
  1. Lina Wolf uploaded patch set 1 08/12/24, 10:42

  2. core-ci voted on patch set 1 V -1 08/12/24, 10:47 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63213

  3. core-ci commented on patch set 1 08/12/24, 10:59 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63213

  4. Lina Wolf uploaded patch set 2 V -1 08/12/24, 11:05

  5. core-ci voted on patch set 2 V +1 08/12/24, 11:10 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63214

  6. Lina Wolf uploaded patch set 3 V +1 08/12/24, 11:39

  7. core-ci voted on patch set 3 V +1 08/12/24, 11:49 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63215

  8. Garvin Hicking commented on patch set 2 08/12/24, 11:50

    Could only have a small look due to vacation this week, but a first comment

    updateCodesnippets.sh:3

    I'm a bit afraid having a duplicate of the yaml file will lead to forgetting the docs counterpart, e.g. for minor spelling fixes. If we keep it a regular task, we should move this to runTests.sh I think. But maybe is there an alternative to prevent having the file? Could we link to github? or enhance render guides to fetch a codesnippet from a github URL?

    Index.rst:13

    IMO we should then move the legacy way to the bottom of the page and not fully remove it, as long as site sits aren't the only way?
  9. Lina Wolf commented on patch set 3 08/12/24, 12:14

    updateCodesnippets.sh:3 Reply

    It would not do to load the file from GitHub. If there are changes to the configuration file those will trigger an imidiate rerendering of the docs. However at that point changes will probably not yet have arrived on GitHub. Also regeneration of codesnippets is a common practice in many docs documents. If we do not choose to copy the file we would have to keep documenting all configuration values manually as we used to and would even be more prone to not update them then if it can be done by running a script.

    Index.rst:13 Reply

    The "legacy" way is not recommended once dropping TYPO3 v12 support and still documented in the older version.
  10. Chris Müller commented on patch set 3 CR -1 08/12/24, 13:10

    Index.rst:11

    The official name is "site sets", IMHO we should use this wording to avoid confusion.

    FluidStyledContent.rst:14

    Here you write "Site Set", below "site set". Pplease stick to one spelling consequently (also other rst files).

    FluidStyledContent.rst:19

    Would prefer "default" over "standard".

    Index.rst:33

    it's -> its

    DefaultTemplate.rst:16

    second "the" is superfluous.

    DefaultTemplate.rst:22

    I would prefer to always use "site set" instead of "set".

    DefaultTemplate.rst:50

    One "custom" should be enough.

    DefaultTemplate.rst:51

    "set" vs "site set" again.
  11. Lina Wolf uploaded patch set 4 CR -1 V +1 08/12/24, 17:36

  12. Lina Wolf commented on patch set 4 08/12/24, 17:38

    Index.rst:11 Reply

    Done

    FluidStyledContent.rst:14 Reply

    Done

    FluidStyledContent.rst:19 Reply

    Done

    Index.rst:33 Reply

    The whole text was wrong, replaced it

    DefaultTemplate.rst:16 Reply

    which "the"?

    DefaultTemplate.rst:22 Reply

    Done

    DefaultTemplate.rst:50 Reply

    Done

    DefaultTemplate.rst:51 Reply

    Done
  13. Lina Wolf uploaded patch set 5 08/12/24, 17:39

  14. Lina Wolf commented on patch set 5 08/12/24, 17:42

    Fixed them all and found some more places still mentioning the old way of configuraiton

    Index.rst:33 Reply

    Done

    DefaultTemplate.rst:16 Reply

    Done
  15. core-ci voted on patch set 4 V +1 08/12/24, 17:44 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63256

  16. core-ci voted on patch set 5 V +1 08/12/24, 17:44 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63257

  17. Garvin Hicking uploaded patch set 6 V +1 08/12/24, 20:18

  18. Lina Wolf commented on patch set 5 08/12/24, 20:18

    updateCodesnippets.sh:3 Reply

    Should we maybe move the question on how the file is copied to its own ticket?

    Index.rst:13 Reply

    According to https://docs.typo3.org/c/typo3/cms-core/main/en-us/Changelog/13.1/Feature-103439-TypoScriptProviderForSitesAndSets.html#set-typoscript it is not recommended to start using the old way once you are using TYPO3 v13. You can of course keep using it if you used it before. But it is still described in the back versions of this document.
  1. Garvin Hicking commented on patch set 6 08/12/24, 20:19

    I changed a few more occurences of "Site Set" to be lowercased, and some more comments.

    updateCodesnippets.sh:3 Reply

    What do you think about changing the render-guides way and allow including files from outside of "Documentation", one level up? Then we could reference `/../Configuration/Sets/FluidStyledContent/settings.definitions.yaml" natively, and not need a "clone" of that file around. Currently render-guides says: ``` [2024-08-12T20:01:54.977549+00:00] app.ERROR: Error while processing "typo3:site-set-settings" directive in "Configuration/Index": Path is outside of the defined root, path: [/../Configuration/Sets/Felogin/settings.definitions.yaml] {"rst-file":"Configuration/Index.rst","currentLineNumber":1} [] ``` The file however would be available (at least when I render locally. I'm not sure how the core docs are triggered; the split-repo of typo3/cms-fluid-styled-content does not have GitHub actions, and I do not know yet where the rendering takes place). IMO that would prevent a lot of trouble of keeping two files in sync. Stefan would also prefer to either try to remove this redundance, but else the task needs to be put into `build/runTests.sh`, and probably we need a CI task that checks if the docs file and the "original" file has the same content. But that would complicate things a lot. Another idea bounced by Lolli: How about putting these yaml definitions into the API docs?! There the "actual" file could be read out, and then we could link to that result from the monorepo-docs...?

    Index.rst:13 Reply

    As mention in another patch, I think: As long as TypoScript setup records are still supported, they still need to be documented. We cannot just remove them, hinting to an old version of the documentation is a problem, if in V13 maybe at some point variables are changed that are still available via TypoScript. I think we will need to keep the TypoScript syntax in here, maybe in a seperate document?
  2. core-ci voted on patch set 6 V +1 08/12/24, 20:25 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63261

  3. Lina Wolf commented on patch set 6 08/12/24, 20:31

    Index.rst:13 Reply

    I dont think we should still recommend to use the typoscript constants as they are only used as a fall back.
  4. Lina Wolf commented on patch set 6 08/12/24, 20:36

    updateCodesnippets.sh:3 Reply

    All over the docs absolute links like /_Snippets/something.xyz go to the documentation folder. We would introduce the very strange situation in which the relative path brings you below the absolute path. I would suggest we delete this script for the time being and just see copying the file as the faster way then manually transforming each entry into a confval?
  5. Garvin Hicking commented on patch set 6 08/12/24, 21:05

    updateCodesnippets.sh:3 Reply

    I'm just a bit concerned to have a duplicate file being around. Personally I just see these choices: * Make render-guides be able to evaluate the "single source of truth" (access the real file). Might be hard and may create security issues, and may break peoples expectation that use render-guides. * Alter the core doc rendering process so that the Action that renders the docs for a sysext performs the copying of the file. So that the duplicate file is NOT part of the repository. Might be hard to see where exactly what is happening and where to change workflows. * Create a CI-integrated way of assuring that the checked in versions of a yaml definition in `Documentation` and `Configuration` match up. Like the SASS/TypeScript assets that are compiled, and fail if no matching JS/CSS is checked in. Maybe this is the best solution also, because then when someone adds new or different options to the site sets file, they cannot merge a change without also addressing the Documentation. This would need to be done via `runTests` and be integrated. This might be the easiest way, but would also involve Stefan/Lolli to agree with.

    Index.rst:13 Reply

    I don't want to say we're "recommending them", but IMO we should be documentating the status quo and state "what is". People may need to look up their config options and might think they misspelled them, while in deed they would be different/right.
  6. Stefan Bürk voted on patch set 6 CR -1 08/14/24, 01:04

  7. Stefan Bürk uploaded patch set 7 CR -1 V +1 08/16/24, 08:54

  8. Stefan Bürk commented on patch set 7 08/16/24, 09:00

    * Removed the file copy command script * Adjusted the site-sets directive to include the site settings definition file using the `PROJECT:` prefix

    updateCodesnippets.sh:3 Reply

    The previous -1 was to talk about that, which I did with Garvin. Lina/Garvin changed the rendering container and introduced a path prefix `PROJECT:` which reflects the starting point of the mounted folder - literally the extension folder. That means, that files of the same extension (or project) does not need to be duplicated (CI/integrity check which failures would anoy contributors), symlinked (maintenance burden) or even a configuration which the rendering container has to move/copy/clone the referenced file. The `PROJECT:` prefix approach is more usable, for the core but also for (public) extension authors who wants to document their extensions - and core can be a good example for it. Thanks for taking care of that (and avoid the burden that we need to add integration and config/code file duplication scripts in the core). Closing this comment thread now.
  9. core-ci voted on patch set 7 V +1 08/16/24, 09:05 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63567

  10. Lina Wolf uploaded patch set 8 V +1 08/16/24, 10:11

  11. Lina Wolf commented on patch set 7 08/16/24, 10:11

    Index.rst:13 Reply

    I rephrased that and put the constants editor back in the menu
  12. Lina Wolf uploaded patch set 9 08/16/24, 10:13

  13. core-ci voted on patch set 8 V +1 08/16/24, 10:17 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63574

  14. core-ci voted on patch set 9 V +1 08/16/24, 10:19 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/63575

  15. Garvin Hicking commented on patch set 9 CR +1 V +1 08/26/24, 08:23

    Fine by me now, others?
  16. Chris Müller commented on patch set 9 08/26/24, 08:42

    One remark: For versionchanged 13.3 is used, but it should be 13.2?
  17. Chris Müller commented on patch set 9 08/26/24, 08:46

    Reply

    Correction: should be 13.1. Site sets for fluid_styled_content were merged on April 22nd, 13.1 was released on April 23rd.
  18. Chris Müller commented on patch set 9 V -1 08/26/24, 08:52

    On it
  19. Chris Müller uploaded patch set 10 CR +1 V +1 08/26/24, 09:19

  20. core-ci voted on patch set 10 V +1 08/26/24, 09:25 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/64186

  21. Chris Müller commented on patch set 10 CR +1 V +1 08/26/24, 09:26

    Reply

    Done

    Reply

    Done
  22. Garvin Hicking commented on patch set 10 CR +1 V +1 08/26/24, 15:08

    Thx, Chris! I'll wait if some of the other reviewers has remarks left and would merge otherwise.
  23. Benjamin Franzke commented on patch set 10 CR +1 V +1 08/27/24, 07:21

    thanks alot!

    Index.rst:43

    Hm, This is fine for now, although we still want a generic template registry like `lib.contentElement` to be configurable via sets, but this still depends on open things/content blocks. So again, might change, but fine for now.
  24. Garvin Hicking voted on patch set 10 CR +2 V +2 08/27/24, 08:06

  25. Garvin Hicking merged patch set 11 08/27/24, 08:06