From 26fb6565372a10fb3dea2c09f9671fb1b1d1d478 Mon Sep 17 00:00:00 2001 From: Nicolai Schirawski Date: Fri, 27 Mar 2026 12:06:35 +0100 Subject: [PATCH 1/6] adds three stubs/articles for the three basic target groups --- Documentation/ForCodeExplorers.rst | 12 ++++++++++++ .../{Environment.rst => ForContributors.rst} | 12 +++++++----- Documentation/ForLiveExplorers.rst | 9 +++++++++ Documentation/Introduction.rst | 5 +++-- 4 files changed, 31 insertions(+), 7 deletions(-) create mode 100644 Documentation/ForCodeExplorers.rst rename Documentation/{Environment.rst => ForContributors.rst} (90%) create mode 100644 Documentation/ForLiveExplorers.rst diff --git a/Documentation/ForCodeExplorers.rst b/Documentation/ForCodeExplorers.rst new file mode 100644 index 00000000..bccc7225 --- /dev/null +++ b/Documentation/ForCodeExplorers.rst @@ -0,0 +1,12 @@ +.. include:: /Includes.rst.txt + +.. _forCodeExplorers: + +================== +For Code-Explorers +================== + +Your use case: you just want to have a look into the code and find examples of best-practices. + +The easiest way is to head to github and inspect the code online: + diff --git a/Documentation/Environment.rst b/Documentation/ForContributors.rst similarity index 90% rename from Documentation/Environment.rst rename to Documentation/ForContributors.rst index 64c9b52a..c26b447b 100644 --- a/Documentation/Environment.rst +++ b/Documentation/ForContributors.rst @@ -1,12 +1,14 @@ .. include:: /Includes.rst.txt -.. _development-environment: +.. _forContributors: -======================= -Development environment -======================= +================ +For Contributors +================ -You can run the code quality checks and automated tests locally (using a +Your use case: You might want to contribute to the tea-extensions. + +You want to run the code quality checks and automated tests locally (using a local PHP, Composer, and database) or using runTests.sh. To kickstart the project, we suggest the usage of the diff --git a/Documentation/ForLiveExplorers.rst b/Documentation/ForLiveExplorers.rst new file mode 100644 index 00000000..c2d5fe4a --- /dev/null +++ b/Documentation/ForLiveExplorers.rst @@ -0,0 +1,9 @@ +.. include:: /Includes.rst.txt + +.. _forLiveExplorers: + +================== +For Live-Explorers +================== + +Your use case: You are developing an own extension and want to add tests to improve your code quality. diff --git a/Documentation/Introduction.rst b/Documentation/Introduction.rst index 6050b853..b3a552d2 100644 --- a/Documentation/Introduction.rst +++ b/Documentation/Introduction.rst @@ -47,8 +47,9 @@ Target group The target group for this extension is **TYPO3 extension developers**. Typical use cases include: -- Gaining inspiration by exploring the code -- Cloning the tea extension locally to access a working example of tests, which can then be adapted for your own extension +- Gaining inspiration by exploring the code :ref:`("code-explorer") ` +- Cloning the tea extension locally to access a working example of tests, which can then be adapted for your own extension :ref:`("live-explorer") ` +- Contributing to the collection of best practices by improving the tea-extension :ref:`("contributors") ` .. _presentation-online-days-2021: From 903b803f6f35c6f6cd49494644c475d9c9a85069 Mon Sep 17 00:00:00 2001 From: Nicolai Schirawski Date: Fri, 27 Mar 2026 16:40:15 +0100 Subject: [PATCH 2/6] update page ForCodeExplorers.rst --- Documentation/ForCodeExplorers.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/Documentation/ForCodeExplorers.rst b/Documentation/ForCodeExplorers.rst index bccc7225..949c653f 100644 --- a/Documentation/ForCodeExplorers.rst +++ b/Documentation/ForCodeExplorers.rst @@ -10,3 +10,7 @@ Your use case: you just want to have a look into the code and find examples of b The easiest way is to head to github and inspect the code online: +.. code-block:: php + + https://github.com/TYPO3BestPractices/tea + From cb673b324ca407ac960117c40f4da70d40165b72 Mon Sep 17 00:00:00 2001 From: Nicolai Schirawski Date: Fri, 27 Mar 2026 16:40:40 +0100 Subject: [PATCH 3/6] update page ForContributors.rst --- Documentation/ForContributors.rst | 49 +++++++++++++++++++++++-------- 1 file changed, 37 insertions(+), 12 deletions(-) diff --git a/Documentation/ForContributors.rst b/Documentation/ForContributors.rst index c26b447b..9968ced3 100644 --- a/Documentation/ForContributors.rst +++ b/Documentation/ForContributors.rst @@ -7,36 +7,56 @@ For Contributors ================ Your use case: You might want to contribute to the tea-extensions. - You want to run the code quality checks and automated tests locally (using a -local PHP, Composer, and database) or using runTests.sh. +local PHP, Composer, and database). + + +.. _clone: -To kickstart the project, we suggest the usage of the +Cloning the distribution +======================== + +To use the full functionality of the tea-extension, you need a surrounding +TYPO3-installation. You might take any installation for that, but we suggest the usage of the `TYPO3-testing-distribution `__ by Oliver Klee as development environment. The distribution comes with a frontend, example data and predefined plugins. -The following commands expect that your SSH key is known by GitHub. If not, you need to use `https://`. + +The following commands expects that you have a GitHub-account and added your SSH key. .. index:: Clone TYPO3 Testing Distribution .. code-block:: bash git clone git@github.com:oliverklee/TYPO3-testing-distribution.git -Please checkout the branch for the TYPO3 version you need. e.g. `12.x`. +Without GitHub-account, clone via https: + +.. code-block:: bash + + git clone https://github.com/oliverklee/TYPO3-testing-distribution.git + + +Please check out the branch corresponding to your required TYPO3 version, for example 12.x. + For more information about the TYPO3-testing-distribution (e.g. backend user credentials), use the documentation: https://github.com/oliverklee-de/TYPO3-testing-distribution/blob/13.x/README.md (TYPO3 13) -Adjust link to your needed version. +Again, adjust the link to the required TYPO3 version. + +.. _clone-tea: + +Cloning the tea extension +========================= +In the same way clone the tea extension. .. index:: Clone Tea Extension .. code-block:: bash git clone git@github.com:TYPO3BestPractices/tea.git -You can organize the folder structure as you wish, but lets say your folder -structure looks like this: +You can organize the folder structure as you wish. It might look similar to this: .. index:: Folder structure .. code-block:: bash @@ -54,9 +74,7 @@ Inside the testing distribution there is a file cp .ddev/docker-compose.extensions.yaml.template .ddev/docker-compose.extensions.yaml -The file needs to mount the tea extension into the testing distribution. Keep in mind -that you use the correct paths here. - +The file mounts the tea extension into the testing distribution. Make sure to insert the correct paths here. .. index:: Mount extension into testing distribution .. code-block:: yaml @@ -64,7 +82,14 @@ that you use the correct paths here. services: web: volumes: - - "$HOME/git/tea:/var/www/html/src/extensions/tea:cached,ro" + - "/tea:/var/www/html/src/extensions/tea:cached,ro" + +Other volumes can safely be deleted. + +.. _start-testing-distribution: + +Start the testing distribution +============================== After that you can start the testing distribution using ddev. From 984d4271025d0676beb6b90769b7c477072029a5 Mon Sep 17 00:00:00 2001 From: Nicolai Schirawski Date: Fri, 27 Mar 2026 16:40:50 +0100 Subject: [PATCH 4/6] update page ForLiveExplorers.rst --- Documentation/ForLiveExplorers.rst | 45 +++++++++++++++++++++++++++++- 1 file changed, 44 insertions(+), 1 deletion(-) diff --git a/Documentation/ForLiveExplorers.rst b/Documentation/ForLiveExplorers.rst index c2d5fe4a..d8ec06cf 100644 --- a/Documentation/ForLiveExplorers.rst +++ b/Documentation/ForLiveExplorers.rst @@ -6,4 +6,47 @@ For Live-Explorers ================== -Your use case: You are developing an own extension and want to add tests to improve your code quality. +Your use case: You are developing your own extension and want to add tests to improve your code quality. + +.. _preparation: + +Preparation +=========== + +Checkout your own extension. + +In the composer.json of your extension add the following parts of the composer.json of the tea-extension: + +* require-dev +* scripts +* scripts-descriptions + +From the config-section of tea-extension, copy these two lines: + +* "vendor-dir": ".Build/vendor" +* "bin-dir": ".Build/bin", + +Copy the folder "Build" (not: ".Build"!) from tea-extension into your extension. + +Merge .gitignore from tea-extension into your extension. + +.. _run-tests: + +Run Tests +========= + +After preparation run: + +.. code-block:: bash + + ./Build/Scripts/runTests.sh -s composer up -W + +Composer should load a long list of dev-dependencies. + +Then use the testing commands. E.g. + +.. code-block:: bash + + ./Build/Scripts/runTests.sh -s composer check:php:stan + + From 535dacdad5aa91bdbd4679ffd6c9b4bc77e2725b Mon Sep 17 00:00:00 2001 From: Nicolai Schirawski Date: Sat, 28 Mar 2026 11:18:55 +0100 Subject: [PATCH 5/6] update page Introduction.rst --- Documentation/Introduction.rst | 25 ++++++++++++++++--------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/Documentation/Introduction.rst b/Documentation/Introduction.rst index b3a552d2..0b1af082 100644 --- a/Documentation/Introduction.rst +++ b/Documentation/Introduction.rst @@ -17,10 +17,15 @@ checks, unit/functional/acceptance testing and continuous integration (CI). .. note:: - This is not a kickstarter extension. + **Never run this extension in production!** + + This extension has educational and documentational purpose only. It is never + meant to run in production. + + This is also not a kickstarter extension. + It should not be used to kickstart other extensions. + Instead, it should serve as an example for best practices. - This extension should not be used to kickstart other extensions. - Instead, this extension should serve as an example for best practices. .. _why-is-this-extension-called-tea: @@ -29,7 +34,7 @@ Why is this extension called "tea"? This extension aims to cover all fundamental aspects of developing an Extbase extension. The fictional use case is the management of tea varieties. The -required models, classes, controllers, and other components represent all +required models, classes, controllers and other components represent all typical parts of an Extbase extension. Additional examples demonstrate how to test these components. @@ -44,12 +49,14 @@ This is not related to the `tea package manager `__. Target group ============ -The target group for this extension is **TYPO3 extension developers**. Typical use -cases include: +The target group for this extension is **TYPO3 extension developers**. + +Typical use cases include: -- Gaining inspiration by exploring the code :ref:`("code-explorer") ` -- Cloning the tea extension locally to access a working example of tests, which can then be adapted for your own extension :ref:`("live-explorer") ` -- Contributing to the collection of best practices by improving the tea-extension :ref:`("contributors") ` +- Gaining inspiration by exploring the code :ref:`("see the code") ` +- Installing the tea-extension without tests to have a simple but comprehensive example at hand ("install the tea extension") +- Using the tests provided by tea extension to improve the code of your own extension :ref:`("use the tests") ` +- Contributing to the collection of best practices by improving the tea-extension :ref:`("contribute to tea-extension") ` .. _presentation-online-days-2021: From 389a47ffe0bf95d3e6bf1841e253c3ce7c782a61 Mon Sep 17 00:00:00 2001 From: Nicolai Schirawski Date: Sat, 28 Mar 2026 16:44:28 +0100 Subject: [PATCH 6/6] [BUGFIX] fix links to new files --- Documentation/Index.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 2c52efa4..395f64c9 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -43,7 +43,9 @@ checks, unit/functional/acceptance testing and continuous integration (CI). :titlesonly: Introduction - Environment + ForCodeExplorers + ForLiveExplorers + ForContributors TechnicalBackground DivergencesToTypo3Core