Review main Merged

84282[DOCS] Improve "_assets" composer directory migration issues

Garvin Hicking CR +2 V +2 Normal +80 −9 updated 05/16/24, 11:54

Commit message

It has come up a few times that users face problems how to properly
utilize the new `_assets/` hashed symlinks for `Resources/Public`
assets of extensions.

The current ChangeLog entry does not mention key searchwords
like `_assets` or `Resources/Public`. Also, vital information is
only available on external blog articles.

This patch tries to provide a central entry point and may
also be ported to the Core-API documentation once the mentioned
concepts are approved by the core-team.

ChangeLog entries are the vital source of truth for migration
instructions and basis for the documentation, thus this is the
first place to be addressed.

Review

  • Code review CR +2 Done
    • Stefan Bürk +2
    • Chris Müller +1
    • Nikita Hovratov +1
    • André Buchmann +1
  • Verified V +2 Done
    • Stefan Bürk +2
    • Chris Müller +1
    • Nikita Hovratov +1
    • André Buchmann +1
    • core-ci +1 CI

Issues 1

Files 1

Review log 2632

Show 57 earlier messages
  1. Garvin Hicking uploaded patch set 1 05/15/24, 14:37

  2. core-ci voted on patch set 1 V +1 05/15/24, 14:41 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/57776

  3. André Buchmann commented on patch set 1 05/15/24, 14:59

    Very nicely written! Thank you very much Some minor improvements: Once you write 'future TYPO3 major versions' and the other time 'future major TYPO3 versions' Maybe also the sentence is a duplicate?

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:17

    plural: files from extensions

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:23

    a directory called :file:`_assets/`
  4. Garvin Hicking uploaded patch set 2 V +1 05/15/24, 15:25

    apply suggestions
  5. Garvin Hicking commented on patch set 2 05/15/24, 15:27

    Reply

    Thanks! :) Indeed that was some redundancy I was't sure how to address. I didn't want to say "as mentioned above" to prevent looking scrolling, and the note is so short. For now I've just unfied this to read "future TYPO3 major versions". Maybe alternate suggestions popup for this, so I leave this unresolved for now.

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:17 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:23 Reply

    Done
  6. core-ci voted on patch set 2 V +1 05/15/24, 15:30 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/57777

  7. Stefan Bürk voted on patch set 2 CR +1 V +1 05/15/24, 16:01

  1. Chris Müller commented on patch set 2 CR -1 05/15/24, 17:21

    Well done 👍

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:18

    No need for the "(s)". HTTP is the protocol - not the scheme, so just use HTTP.

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:20

    images/icons (lowercase)

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:26

    MD5 hash (without dash)

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:28

    composer -> Composer (common name)

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:33

    Personally, would remove the preceding slash before public to avoid confusion with absolute path.

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:34

    Here too (avoid preceding slash).

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:35

    And here (avoid preceding slash).

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:42

    "JavaScipt files" (without dash)

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:43

    Avoid preceding slash in path

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:47

    Dow we now have a fluid text role?

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:60

    Had to read this sentence multiple times to get what is meant, maybe write it better?

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:74

    Alternative -> Alternatively

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:82

    Not only that, it also changes currently when using another vendor folder than "vendor" (as this is taken int account for the MD% hash). So a developer changing that for whatever reason may break integrator's work.

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:83

    composer -> Composer

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:91

    Thanks for linking 😊

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:92

    use a :ref: here
  2. Garvin Hicking uploaded patch set 3 CR +1 V +1 05/15/24, 19:49

    Apply suggestions from code review
  3. Garvin Hicking commented on patch set 3 05/15/24, 19:50

    Thanks @typo3@brotkrueml.dev for the eagle eyes, addressed your suggestions! :)

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:18 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:20 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:26 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:28 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:33 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:34 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:35 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:42 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:43 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:47 Reply

    Don't now if it's new, but yes, it exists and gets rendered :-)

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:60 Reply

    I see. I tried to shorten the sentence and reword it a bit to get my idea across, did that help?

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:74 Reply

    Thanks, actually I reworded the sentence because I think it also was not clear enough.

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:82 Reply

    Good addition, I tried to address this with another sentence.

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:83 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:92 Reply

    Could you remind me again; the docs often use absolute links to docs.typo3.org - when do I use an absolute link and when a reference? Are the absolute link places just an oversight? (e.g. in Feature-94625)
  4. core-ci voted on patch set 3 V +1 05/15/24, 19:54 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/57787

  5. Garvin Hicking uploaded patch set 4 V +1 05/15/24, 19:55

  6. core-ci voted on patch set 4 V +1 05/15/24, 20:00 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/57788

  7. Nikita Hovratov commented on patch set 4 05/15/24, 20:43

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:28

    its

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:48

    You probably meant stdWrap insertData in combination with data `path` https://docs.typo3.org/m/typo3/reference-typoscript/main/en-us/Functions/Data.html#path I would mention this data getter as the primary method in TypoScript.
  8. Christoph Lehmann commented on patch set 4 05/15/24, 21:05

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:79

    May mention EXT:typo3_console ? It has a command to get all paths ./bin/typo3 frontend:asseturl +-------------------------+--------------------------------------------+ | extension key | asset URL | +-------------------------+--------------------------------------------+ | core | /_assets/1ee1d3e909b58d32e30dcea666dd3224/ |
  9. Garvin Hicking commented on patch set 4 05/15/24, 21:15

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:79 Reply

    That's a good idea, I would however prefer to add this to the Documentation port later, to keep the ChangeLog here with a "vital" scope? The extensions can be retrieved by inspecting the symlinks so it would be more of a convenience method to mention later?
  10. André Buchmann commented on patch set 4 05/16/24, 06:22

    Reply

    I'm fine with the unification and having it twice as it's a kinda long text with a lot of informations.
  11. Garvin Hicking uploaded patch set 5 V +1 05/16/24, 06:38

    Apply suggestions from code review
  12. Garvin Hicking commented on patch set 5 05/16/24, 06:38

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:28 Reply

    Done

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:48 Reply

    Yes, I improved this by also linking to the specific functions now.
  13. core-ci voted on patch set 5 V +1 05/16/24, 06:43 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/57822

  14. André Buchmann voted on patch set 5 CR +1 V +1 05/16/24, 07:16

  15. Chris Müller commented on patch set 5 CR -1 05/16/24, 07:51

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:60 Reply

    "You can use ... to generated variables" -> better: "You can use ... to create variables"? Does that fit what you want to say? Additionally, in the second line you have a superfluous colon before EXT:...
  16. Christoph Lehmann commented on patch set 5 05/16/24, 07:53

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:79 Reply

    absolutely fine!
  17. Christoph Lehmann wrote 05/16/24, 07:58

    Removed cc Christoph Lehmann.
  18. Garvin Hicking uploaded patch set 6 CR +1 V +1 05/16/24, 08:51

    apply code review suggestion
  19. Garvin Hicking commented on patch set 6 05/16/24, 08:52

    Important-98484-ExtensionsOutsideOfDocumentRootForComposer-basedTYPO3Installations.rst:60 Reply

    I replaced this with "create". The superfluous colon was adressed in a prior patch already, which isn't reflected in this gerrit comment here (due to it being releated to patchset 2) - should be good now?
  20. core-ci voted on patch set 6 V +1 05/16/24, 08:56 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/57824

  21. Chris Müller commented on patch set 6 CR +1 V +1 05/16/24, 09:11

    👍
  22. André Buchmann voted on patch set 6 CR +1 V +1 05/16/24, 09:13

  23. Stefan Bürk voted on patch set 6 CR +2 V +2 05/16/24, 09:54

  24. Nikita Hovratov voted on patch set 6 CR +1 V +1 05/16/24, 11:11

  25. Stefan Bürk merged patch set 7 05/16/24, 11:54