Review main Merged

58388[TASK] Update INSTALL.md and README.md

Josef Glatz CR +2 V +2 Hard +95 −377 updated 11/22/18, 07:49

Commit message

The main goal of this patch is to update the neglected
INSTALL.md and README.md to represent the current
state of the requirements and to improve the overall
content of the two "entry" documentation files.

The install.md has been massively shortened and links to
the official guides were added to finally be able to have
one source of truth.

Review

  • Code review CR +2
    • Susi Moog +2
    • Benni Mack +1
  • Verified V +2
    • Susi Moog +2
    • Benni Mack +1
    • TYPO3com +1 CI

Issues 1

Files 2

Review log 3946

Show 2021 earlier messages
  1. Josef Glatz uploaded patch set 1 09/25/18, 11:57

  2. Josef Glatz commented on patch set 1 09/25/18, 11:59

    Hey folks! i would like to get some first feedback on my draft if I should continue my work AND open to any suggestions what should be fundamentally changed in the two files
  3. Josef Glatz wrote 09/25/18, 12:00

    Topic set to readme
  4. Josef Glatz commented on patch set 1 09/25/18, 12:24

    INSTALL.md:23

    Should we add minimum version numbers for Chrome, Firefox and Safari?

    INSTALL.md:24

    Should we mention, that the main goal is to make the TYPO3 backend working even in "older" browers and it's ok if some styling is not 100% good.

    INSTALL.md:41

    Re-think disk space specification (Core needs about ~200MB on disk without exts and without DB). Do we still need that info? Should we mention something like "200MB for a running TYPO3 instance + user assets/files + database + extensions + and other additional code?

    INSTALL.md:42

    why do we not only suggest GM?

    INSTALL.md:54

    Should we split up DBMS specific requirements completeley into segments?

    INSTALL.md:57

    Should we rewrite this part to a generic form? If yes: I don't have knowledge of sqlite, ... I would need some help here from the db pro's

    INSTALL.md:59

    Can I simply use "database user" instead of "MySQL user"?

    INSTALL.md:106

    I think we should definitely add dedicated documentation to docs.typo3.org and link them here. Such an enterprise cms needs such docu.

    INSTALL.md:112

    Do we need something else for the core url handling stuff?

    INSTALL.md:114

    Is it ok to mention MariaDB for the "best performance" scenario?

    INSTALL.md:119

    another version than 7.2 is not officially tested. Let's updated this, whenever the core supports 7.3. It's just not good to say something which we can not promise

    INSTALL.md:127

    This points must be updated in context of the related PHP version 7.2. Do I miss something here?

    INSTALL.md:134

    Do I miss any other optional extension to support another supported dbms?

    INSTALL.md:219

    When do we ship nginx ready configurations for TYPO3 ? are there any plans? earlybird.at says they using nginx without problems..

    INSTALL.md:329

    Is this bulletpoint valid? Should I rephrase it?

    INSTALL.md:358

    Should we drop that, as TYPO3 is compatible with strict-mode of MySQL

    README.md:14

    I think mentioning MySQL is nowadays still the best possibility here)

    README.md:25

    Should we add any other often used webserver which I forgot?

    README.md:30

    Is that correct?

    README.md:53

    Should we add/remove here any DBMS?

    README.md:68

    I removed wiki.typo3.or as it will be removed in "near" future

    README.md:84

    I think it's good to directly mention the TER to get an overview of available 3rd party exts in the TYPO3 universe (beside packagist)

    README.md:117

    I think it's OK to mention that there is not so much traffic

    README.md:119

    Added the new url. Should we add a shorturl at t3o?

    README.md:121

    Should we mention the actual ways of where to host extensions nowadays?

    README.md:133

    Maybe this text could be improved. I think also about a special channel on slack, where people can ask for such stuff?

    README.md:158

    I think this is something which could be removed as it doesn't help anybody. Mostly newcomers read those documents - so it make no sense to me. But yes, we could leave that.
  5. Josef Glatz updated the commit message in patch set 2 09/25/18, 12:25

  6. Josef Glatz wrote 09/25/18, 12:41

    Removed reviewer Susi Moog.
  7. Sybille Peters commented on patch set 2 09/25/18, 13:55

    I added some comments. Additionally, I think installation via composer is neglected in the INSTALL.md. Also, it might be a good idea to add extra links at the bottom to additional information like the requirements page (https://typo3.org/cms/requirements/) and to the installation & upgrade guide (https://docs.typo3.org/typo3cms/InstallationGuide/), which probably should be reviewed as well.

    INSTALL.md:43

    The sentence about MariaDB and Percona was removed here. In the list above, only MariaDB was mentioned, not Percona. I assume Percona is still supported. Maybe better to mention in the list above: any MySQL compatible DB engine like MariaDB or Percona? Or "or any database system supported by Doctrine DBAL" as mentioned in https://typo3.org/cms/requirements/

    INSTALL.md:72

    According to the core install/Classes/SystemEnvironment/Check.php recommended memory_limit is 128M.

    INSTALL.md:111

    I believe you also need mod_rewrite if you don't use realurl.

    INSTALL.md:114

    You write MySQL 5.5 here, but >= 5 above.

    INSTALL.md:119

    You write 7.2 here, but >= 7.2 above.

    INSTALL.md:125

    You might want to just check if OPCache is enabled by default: opcache.enable=1, http://php.net/manual/en/opcache.configuration.php

    INSTALL.md:140

    "throws out warnings" sounds weird. Better: "throws exceptions" or " causes warnings"
  8. Susi Moog commented on patch set 2 09/25/18, 18:38

    INSTALL.md:49

    Add sentence about _web.config example file for IIS?

    INSTALL.md:54

    InnoDB is only relevant to some databases (mysql and mariadb?).

    INSTALL.md:59

    rewrite to generic user rights instead of mysql specific

    INSTALL.md:72 Reply

    minimum is 64, recommended is 128, maybe add both?

    INSTALL.md:74

    Qualify to: when using Apache:

    INSTALL.md:99

    these need updates, too. Mysqli --> only when using mysql obviously. as for the others: are there version without "SPL/standard"? core composer json states the following as required: "ext-PDO": "*", "ext-json": "*", "ext-pcre": "*", "ext-session": "*", "ext-xml": "*", and these as suggestion: "ext-gd" "ext-fileinfo "ext-zlib" "ext-intl" "ext-openssl" "ext-zip"

    INSTALL.md:111 Reply

    - in v9 with url routing you at least need it if you have a site config - I'm not sure we should still recommend Apache as "best" setup

    INSTALL.md:125 Reply

    I would not recommend adding another opcache on top of PHPs default one.

    INSTALL.md:151

    we should add something about a composer based setup (which I'd consider recommended) somewhere.

    INSTALL.md:242

    are

    README.md:117

    I'd actually remove the mention of these two.

    README.md:131

    #typo3-cms-coredev

    README.md:133

    get you up and running?
  9. Susi Moog commented on patch set 2 09/25/18, 18:48

    INSTALL.md:23 Reply

    I wouldn't, we'd only forget to update these and basically we communicate "latest"

    INSTALL.md:24 Reply

    hmm, basically the goal is to have a browser everyone can have, but for everything except IE11 I'd rather promote updating (on IE11 that may sometimes be impossible)

    INSTALL.md:41 Reply

    Core with tests or package? I'd add something sensible / recommended here, for people looking for hosting providers etc.

    INSTALL.md:42 Reply

    Because these are `requirements` not only recommendations and if people have a server with IM they should still know that they'll be able to use that.

    INSTALL.md:59 Reply

    I think so (for the other part, see my comment on patch set 2)

    INSTALL.md:106 Reply

    yes and stop linking to the wiki with random untested hints from people for topics such as performance ;)

    INSTALL.md:112 Reply

    nope, mod_rewrite / url rewriting it is

    INSTALL.md:114 Reply

    for the best performance scenario I'm not even sure if that wouldn't be postgres or something, I'd rather correct the sentence above to: this is a basic recommended setup: (and leave the performance part out of it, as that largely depends on other factors, especially since we are using doctrine now - and neither mysql nor mariadb are especially known for high-performance in comparison).

    INSTALL.md:134 Reply

    I'm using extension=pdo_sqlsrv for sqlsrv instead of sqlsrv itself, not sure if that's relevant.

    INSTALL.md:219 Reply

    see https://forge.typo3.org/issues/54316 - whenever that one is tackled. the problem is in comparison with apache and IIS we cannot provide a file that you can simply rename in the project dir and be ready, it would just be an example config people need to add to their server setup.

    INSTALL.md:329 Reply

    Probably, for example it would be a good idea to make the whole core non-writable.

    INSTALL.md:358 Reply

    yes.
  10. Daniel Siepmann commented on patch set 2 09/26/18, 05:54

    We could switch to rst and make use of `.. contents:: :local:` this way we can have a table of contents listing out of the box, e.g. at Github. For an example you can check https://github.com/DanielSiepmann/testing-talk/blob/a507875/readme.rst
  11. Josef Glatz commented on patch set 2 09/26/18, 06:02

    Thanks for your replies! Many thanks! I push a new one with all your inputs during the day
  12. Daniel Siepmann commented on patch set 2 09/26/18, 06:13

    INSTALL.md:23

    Apple renamed MacOS X to "macOS"

    INSTALL.md:41

    This depends on the type of installation. If you are using composer, only required system extensions are installed, which can result in smaller installations. Also I didn't check the actual installation size with all necessary dependencies.

    INSTALL.md:73

    As some Unix Distrbutions deliver their own defaults, not all might have a appropriate xdebug.max_nesting_level value. Do we want to give a hint for development environments with xdebug?

    INSTALL.md:114 Reply

    This is the recommended setup, above was the minimum required setup. So this might be correct.

    INSTALL.md:116

    This is now already in the reuired setup and can be removed here.

    INSTALL.md:119 Reply

    Probably this can just be removed here.

    INSTALL.md:125 Reply

    Some Unix distributions come with their own defaults. So PHP defaults are not necessary the defaults for installed PHP versions.

    README.md:26

    Apple renamed MacOS X to "macOS"

    README.md:47

    I would not list the information twice. I would keep a link to the INSTALL.md instead. Otherwise we have multiple places and need to update all of them in the future.
  13. Susi Moog commented on patch set 2 09/26/18, 07:51

    INSTALL.md:125 Reply

    My point was more, do not promote zend optimizer or wincache on top of PHPs internal OpCache (nothing really todo with distribution defaults, but with the fact that PHP Core has an opcache already)
  14. Josef Glatz uploaded patch set 3 09/30/18, 19:53

  15. Josef Glatz commented on patch set 2 09/30/18, 19:53

    INSTALL.md:23 Reply

    Done

    INSTALL.md:49 Reply

    Done

    INSTALL.md:54 Reply

    Done

    INSTALL.md:59 Reply

    Done

    INSTALL.md:72 Reply

    Done

    INSTALL.md:72 Reply Unresolved

    Done

    INSTALL.md:73 Reply

    I would add that to the contribution workflow AND/OR install documentation on docs.typo3.org

    INSTALL.md:74 Reply

    Done

    INSTALL.md:99 Reply

    Done
  16. TYPO3com voted on patch set 3 V +1 09/30/18, 20:28 Completed build in 23m 08s on Sun, 30 Sep, 10:28 PM Test Summary: 36913 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29080

  17. Josef Glatz uploaded patch set 4 09/30/18, 20:59

  18. Josef Glatz commented on patch set 2 09/30/18, 21:00

    INSTALL.md:41 Reply

    Thx! As a first step I've add info that it depends on the install method

    INSTALL.md:73 Reply

    Done

    INSTALL.md:74 Reply

    Done

    INSTALL.md:111 Reply

    I have moved mod_rewrite to the basic requirements with an hint as this is something almost every TYPO3 website uses.

    INSTALL.md:111 Reply Unresolved

    Done

    INSTALL.md:114 Reply

    Done

    INSTALL.md:114 Reply Unresolved

    5.5 is already correct (\TYPO3\CMS\Install\SystemEnvironment\DatabasePlatform\MySqlCheck::$minimumMySQLVersion)

    INSTALL.md:119 Reply

    Done

    INSTALL.md:119 Reply Unresolved

    Done

    INSTALL.md:125 Reply

    Done

    INSTALL.md:125 Reply

    Done

    INSTALL.md:125 Reply

    Done

    INSTALL.md:125 Reply Unresolved

    Do you want to mention something like: "(make sure opcache is enabled in php.ini)"

    INSTALL.md:140 Reply Unresolved

    Done

    INSTALL.md:242 Reply

    Done
  19. Josef Glatz commented on patch set 2 09/30/18, 21:09

    README.md:26 Reply

    Done

    README.md:47 Reply

    Done

    README.md:117 Reply

    Done

    README.md:131 Reply

    This is the anchor link to the header Chat with us ;) I've added additional info to it, thx!

    README.md:133 Reply

    added your text. please recheck in my upcoming patchset. thx susi!
  20. Josef Glatz uploaded patch set 5 09/30/18, 21:11

  21. Josef Glatz uploaded patch set 6 09/30/18, 21:22

  1. Josef Glatz commented on patch set 2 09/30/18, 21:24

    INSTALL.md:43 Reply Unresolved

    Eagle Eye!! ツ At the moment, PerconaDB isn't supported officially as far as I can see. Even not all Doctrine DBAL supported DBMS's aren't support AFAIK. But I will kindly ask Benni/Susi to take that into account while proof reading
  2. TYPO3com voted on patch set 4 V +1 09/30/18, 21:36 Completed build in 28m 20s on Sun, 30 Sep, 11:36 PM Test Summary: 36913 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29094

  3. TYPO3com voted on patch set 5 V +1 09/30/18, 21:45 Completed build in 16m 54s on Sun, 30 Sep, 11:45 PM Test Summary: 36913 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29097

  4. TYPO3com voted on patch set 6 V +1 09/30/18, 21:53 Completed build in 25m 39s on Sun, 30 Sep, 11:53 PM Test Summary: 36913 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29098

  5. Josef Glatz wrote 10/01/18, 04:28

    Assignee added: Benni Mack <benni@typo3.org>
  6. Josef Glatz wrote 10/01/18, 04:29

    Assignee deleted: Benni Mack <benni@typo3.org>
  7. Stephan Großberndt commented on patch set 6 10/01/18, 05:48

    INSTALL.md:38

    People who don't know MariaDB is a [binary compatible drop in replacement](https://mariadb.com/kb/en/library/mariadb-vs-mysql-compatibility/) the current list of versions makes it look like MariaDB is only supported with 10.2+ while it is since 5.1 Also see https://github.com/TYPO3-infrastructure/get.typo3.org/issues/18#issuecomment-418386482 where this has been discussed. INSTALL.md, https://get.typo3.org/version/9#system-requirements and https://typo3.org/cms/requirements/ need to be updated and synchronized
  8. Stephan Großberndt commented on patch set 6 10/01/18, 05:56

    INSTALL.md:118

    Since PHP7 it is no longer called mysqli but mysql IIRC - will check

    INSTALL.md:236

    Is this still true?
  9. Georg Ringer commented on patch set 6 10/01/18, 09:50

    can also take care of being in sync with get.typ3.org? thx
  10. Susi Moog uploaded patch set 7 10/01/18, 17:54

  11. Susi Moog uploaded patch set 8 10/01/18, 17:56

  12. Susi Moog commented on patch set 8 10/01/18, 17:57

    after a short discussion we decided to mainly remove the texts in the install.md. I will update my PR to the install guide to include the missing information there but this way we have a single source of truth.
  13. TYPO3com voted on patch set 7 V +1 10/01/18, 18:08 Completed build in 13m 49s on Mon, 1 Oct, 08:08 PM Test Summary: 36913 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29213

  14. Benni Mack voted on patch set 8 V +1 CR +1 10/01/18, 18:09

  15. Josef Glatz commented on patch set 8 10/01/18, 18:09

    > Patch Set 8: > > after a short discussion we decided to mainly remove the texts in the install.md. I will update my PR to the install guide to include the missing information there but this way we have a single source of truth. Great decision!
  16. Josef Glatz voted on patch set 8 CR -1 10/01/18, 18:13

  17. TYPO3com voted on patch set 8 V +1 10/01/18, 18:14 Completed build in 16m 35s on Mon, 1 Oct, 08:14 PM Test Summary: 36913 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29215

  18. Josef Glatz updated the commit message in patch set 9 10/01/18, 18:15

  19. Benni Mack voted on patch set 9 V +1 CR +1 10/01/18, 18:21

  20. Susi Moog commented on patch set 9 10/01/18, 18:21

  21. TYPO3com voted on patch set 9 V +1 10/01/18, 18:32 Completed build in 12m 39s on Mon, 1 Oct, 08:32 PM Test Summary: 36928 passed Find logs and detail information at https://bamboo.typo3.com/browse/CORE-GTC-29220

  22. Susi Moog voted on patch set 9 V +2 CR +2 10/01/18, 18:41

  23. Susi Moog merged patch set 10 10/01/18, 18:41

  24. Oliver Hader commented on patch set 10 11/21/18, 16:18

    Where do I find supported browsers for TYPO3 v9 now?
  25. Susi Moog commented on patch set 10 11/22/18, 07:49

    @Olly browsers count as "system requirements" -> INSTALL.md says: https://get.typo3.org/version/9#system-requirements