Review main Merged

72288[TASK] Improve sysext metadata

Sybille Peters CR +2 V +2 Hard +436 −176 updated 11/27/21, 22:23

Commit message

The title and description texts as well as the README.rst for
system extensions are unified and some texts updated to
reflect changes.

Since the description and README.rst are also displayed on
Packagist, the text should be chosen so that it helps
people not familiar with TYPO3 know what the package is
about (e.g. by preceding the description with "TYPO3 CMS").

Descriptive texts for extensions are in these files:

- composer.json
- ext_emconf.php
- README.rst

The information is displayed in the Extension Manager (ext_emconf.php),
on extensions.typo3.org, on Packagist (composer.json and README.rst)
and on GitHub (README.rst).

We reuse the same text blocks in the following manner:

1. Extension title - used in ext_emconf.php:title and composer.json:
   description
2. Extension description (short) - used in ext_emconf.php:description
   and composer.json:description
3. Title and extension description (long) - used in README.rst. In
   most cases, the short description is reused, in some cases it is
   augmented with more information.

In composer.json, the description consists of: '<title> - <description>'

Also,

- In the title all words are capitalized (common name)
- The title always starts with "TYPO3 CMS"
- The description ends with a period.

Review

  • Code review CR +2 Done
    • Christian Kuhn +2
    • Stefan Bürk +1
  • Verified V +2 Done
    • Christian Kuhn +2
    • Stefan Bürk +1
    • core-ci +1 CI

Issues 1

Files 104

Show 84 more files

Review log 2637

Show 1012 earlier messages
  1. Sybille Peters uploaded patch set 1 11/25/21, 16:30

  2. Andreas Kienast commented on patch set 1 11/25/21, 16:39

    Why do you have different descriptions in composer.json than in ext_emconf.php? What's the benefit?
  3. core-ci voted on patch set 1 V +1 11/25/21, 16:40 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19745

  4. Sybille Peters commented on patch set 1 11/25/21, 16:43

    Reply

    No, that was not the intention. In fact my intention was to unified it. The only difference should be that composer.json should use the title AND the description from ext_emconf.php (<title> - <description>). Please point out via comment where there is a difference.
  5. Mathias Brodala commented on patch set 1 CR -1 11/25/21, 16:57

    Please don't be overwhelmed by my comments, I cannot express how much I love that one (you) finally tackles this. Thus I tried to make suggestions which can improve the descriptions even further.

    composer.json:4

    This sounds confusing when read together. This IS the TYPO3 backend after all, so maybe we can improve this.

    composer.json:4

    Maybe "TYPO3 backend"?

    composer.json:4

    "TYPO3 backend"?

    composer.json:4

    The "library" should be dropped here since this package is much more than a library.

    composer.json:4

    > Module in the TYPO3 backend for configurable dashboards with widgets

    composer.json:4

    TYPO3 backend

    composer.json:4

    TYPO3 frontend plugins

    composer.json:4

    framework

    composer.json:4

    Maybe we can also unify "module", "backend module" and "user interface" (See "Log")?

    composer.json:4

    TYPO3 frontend

    composer.json:4

    See my "module" remark above.

    composer.json:4

    > Additional metadata for files

    composer.json:4

    > the Fluid templating engine I'd avoid the package name here since it can change.

    composer.json:4

    > Flexible TYPO3 frontend form framework with TYPO3 backend editor

    composer.json:4

    See above; this IS the TYPO3 frontend.

    composer.json:4

    This really should be shortened; especially the format part can be dropped here IMO since it's not important that early.

    composer.json:4

    > as well as files like PDF, Word, HTML and plain text.

    composer.json:4

    > pages and records

    composer.json:4

    Not sure: didn't we try to avoid abbrev., I mean abbreviations? ;-)

    composer.json:4

    > administration and setup

    composer.json:4

    I'd vote for keeping the term "Install Tool" simply due to the fact that there's still an /install.php. The additional explanation "Admin tools" can be kept as explanation Not sure what the consensus is here.

    composer.json:4

    > checks for broken links

    composer.json:4

    IMO this part can be dropped. And/or the remaining part shortened.

    composer.json:4

    > Open Docs Maybe?

    composer.json:4

    TYPO3 backend

    composer.json:4

    > TYPO3 backend

    composer.json:4

    > HTTP

    composer.json:4

    > with optional But TBH this is already too specific IMO, so maybe we can drop this.

    composer.json:4

    > for the TYPO3 Backend People continously ask about CKEditor integration for the frontend. We should try to not mislead them that this package does that.

    composer.json:4

    > including sitemaps This is so important that it should be mentioned IMO.

    composer.json:4

    > System Notes Maybe?

    composer.json:4

    > TypoScript Template Maybe?

    composer.json:4

    TYPO3 backend

    composer.json:4

    Explaining "workspaces" with "workspaces" is not that useful IMO. ;-) Maybe we can add a short explanation what workspaces actually are, or rephrase this for "workflows" instead.
  6. Lina Wolf commented on patch set 1 CR -1 11/25/21, 17:06

    Please have a look at my comments

    composer.json:4

    Actually fluid-styled-content only contains the templates and some css. The content elements themselves are created in EXT:frontend.

    composer.json:4

    actually by default it produces XML nowadays.

    composer.json:4

    Should we mention the plugin etc? Is is more then just the search engine

    composer.json:4

    I think it also includes the installer to install a new TYPO3 instance? The 1,2,3 installer?

    composer.json:4 Reply

    Why would you consider the sitemap more important then i.e. metadata...?

    composer.json:4

    "for the CMS frontend in." the sentence seems not complete?
  7. Mathias Brodala commented on patch set 1 11/25/21, 17:07

    composer.json:4 Reply

    I'd not say "more" but "equally".
  8. Sybille Peters uploaded patch set 2 11/25/21, 18:18

  9. Sybille Peters commented on patch set 1 11/25/21, 18:18

    First batch. Resolved some comments. Working on next batch ...

    Reply

    No, is cool. Maybe you can also look in the commit message if you agree with the general procedure (e.g. use same texts in ext_emconf and composer.json, always start title with "TYPO3" etc).

    composer.json:4 Reply

    Agree. Finding a good phrase for some of these is not so easy. Maybe someone can improve further .... My next idea was "Functionality for administration and editing in the TYPO3 backend." but it is more or less the same, removed it for now - same as in "TYPO3 Frontend".

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    I am not sure what you mean. Maybe you mean sometimes "user interface" is used, sometimes "backend module" etc? So we should always use (preferably) the same terms? But sometimes it is more than just a backend module (e.g. redirects extension, maybe also extension manager and filelist provide more functionality than just a BE module). So rather something generic like TYPO3 backend should be used. And we need to decide on a case by case basis. Problem is, I often don't know exactly if it just a backend module or more. Will fix the other stuff first ... Maybe others can make suggestions.

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    I decided now to remove the additional description entirely. Just writing TYPO3 Frontend in other words is awkward. Describing all the "TYPO3 Frontend" does would be too long and prone to change. Can be changed, if someone has a better idea.

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Not sure if there is a consensus. I will follow your suggestion.

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    ok, done. I just remembered this also includes the lowlevel cleaner. I am not aware of the full feature list of this extension.

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Would it not be helpful to specifically list the module?

    composer.json:4 Reply

    Actually both are optional, right?

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Agree. I rephrased it. I will try to get feedback from someone who knows this extension better :)
  10. core-ci voted on patch set 2 V +1 11/25/21, 18:31 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19751

  11. Sybille Peters uploaded patch set 3 11/25/21, 18:42

  12. Sybille Peters commented on patch set 2 11/25/21, 18:43

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    The description in composer.json was shortened. A longer text now exists in the README.rst and contains XML and t3d.

    composer.json:4 Reply

    Agree. Also, "Search engine" is a little misleading, I would usually think of a standalone search engine. Also, as listed in the README.rst, there is also a BE module. So it is indexing functionality, a search plugin and BE module (possibly more). I shortened the text. The longer text is in the README.rst!

    composer.json:4 Reply

    I changed "for system administration and setup" to for "installation, upgrade, system administration and setup". I don't know if we have to mention the installer separately, but that could go in the README.rst in the longer description. Please see my changes in the README.rst. Since this extension really offers a lot, it is a little difficult to find a description.

    composer.json:4 Reply

    Done
  1. Sybille Peters commented on patch set 3 11/25/21, 18:44

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done
  2. Sybille Peters uploaded patch set 4 11/25/21, 18:47

  3. Sybille Peters uploaded patch set 5 11/25/21, 18:49

  4. core-ci voted on patch set 3 V +1 11/25/21, 18:55 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19752

  5. core-ci voted on patch set 4 V +1 11/25/21, 19:01 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19753

  6. Sybille Peters uploaded patch set 6 11/25/21, 19:05

  7. core-ci voted on patch set 5 V +1 11/25/21, 19:05 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19754

  8. Sybille Peters uploaded patch set 7 11/25/21, 19:08

  9. core-ci voted on patch set 6 V +1 11/25/21, 19:19 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19755

  10. core-ci voted on patch set 7 V +1 11/25/21, 19:22 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19756

  11. Sybille Peters uploaded patch set 8 11/26/21, 01:44

  12. core-ci voted on patch set 8 V +1 11/26/21, 02:00 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19775

  13. Alexander Nitsche commented on patch set 8 CR -1 11/26/21, 09:01

    In general i think this is a very good idea to unify the texts here. In particular i checked only EXT:impexp.

    README.rst:11

    I would revert the changes in the second sentence and merge both sentences again to become: "Tool for importing and exporting records [in TYPO3] using XML or the custom serialized format T3D." My reasons: 1) I would not put the T3D format in parentheses nor format it like a file extension. It should be completely aligned with XML. 2) The second part of the second phrase is quite redundant as we already said that the tool is importing and exporting records. 3) The second phrase should not start with "Uses ..".

    composer.json:4

    1) "Tool for importing (..) records from TYPO3." -> would consider to remove "remove TYPO3" as it does not work with import, or make it a neutral "in TYPO3". 2) There are some places in the extension, where the term "Import/Export" is used: will you adjust these too?
  14. Sybille Peters commented on patch set 8 11/26/21, 09:23

    README.rst:11 Reply

    I have used the suggestion without the [in TYPO3].

    composer.json:4 Reply

    1) Actually on second thought, I think the "from TYPO3" is redundant. It is vague. And as you pointed out not entirely correct. Will remove. 2) Not scope of patch to change other files. But if this causes too many problems or followup patches we can revert and call it "Import/Export" again instead of "Import & Export" I have changed it.
  15. Sybille Peters uploaded patch set 9 11/26/21, 09:23

  16. core-ci voted on patch set 9 V +1 11/26/21, 09:36 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19781

  17. Alexander Nitsche commented on patch set 9 V +1 CR +1 11/26/21, 09:45

    Only checked EXT:impexp.
  18. Sybille Peters uploaded patch set 10 11/27/21, 16:50

  19. Sybille Peters commented on patch set 10 11/27/21, 16:51

    composer.json:4 Reply

    Sticking with the short variant now: "TYPO3 CMS backend"

    composer.json:4 Reply

    Rachel mentioned that it might be helpful to see if an extension provides BE modules etc. to see how to enact with it and > The description should also help a end user decide if he/she needs to activate/install the extension via composer or the extension manager, for instance the recycler or the workspaces > What I need to know when I discover an extension is if it provides be modules, fe plugins, services, dashboard widgets, etc. So I decided to specifically list the BE modules and unified this some more.

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Done

    composer.json:4 Reply

    Change the text some more: > Create redirects manually, list existing redirects and automatically create redirects on slug changes.

    composer.json:4 Reply

    I have now used to documentation https://docs.typo3.org/c/typo3/cms-seo/11.3/en-us/Introduction/Index.html and changed the text some more.
  20. core-ci voted on patch set 10 V -1 11/27/21, 17:04 Core CI is not happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19874

  21. core-ci voted on patch set 10 V +1 11/27/21, 17:12 Core CI is happy: https://git.typo3.org/typo3/CI/cms/-/pipelines/19874

  22. Christian Kuhn commented on patch set 10 V +1 CR +1 11/27/21, 20:40

    nice systematic change. let's get it done!
  23. Stefan Bürk voted on patch set 10 V +1 CR +1 11/27/21, 20:41

  24. Christian Kuhn voted on patch set 10 V +2 CR +2 11/27/21, 22:23

  25. Christian Kuhn merged patch set 11 11/27/21, 22:23