diff --git a/Documentation/ForCodeExplorers.rst b/Documentation/ForCodeExplorers.rst new file mode 100644 index 00000000..949c653f --- /dev/null +++ b/Documentation/ForCodeExplorers.rst @@ -0,0 +1,16 @@ +.. 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: + +.. code-block:: php + + https://github.com/TYPO3BestPractices/tea + diff --git a/Documentation/Environment.rst b/Documentation/ForContributors.rst similarity index 53% rename from Documentation/Environment.rst rename to Documentation/ForContributors.rst index 64c9b52a..9968ced3 100644 --- a/Documentation/Environment.rst +++ b/Documentation/ForContributors.rst @@ -1,40 +1,62 @@ .. include:: /Includes.rst.txt -.. _development-environment: +.. _forContributors: -======================= -Development environment -======================= +================ +For Contributors +================ -You can run the code quality checks and automated tests locally (using a -local PHP, Composer, and database) or using runTests.sh. +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). -To kickstart the project, we suggest the usage of the + +.. _clone: + +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 @@ -52,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 @@ -62,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. diff --git a/Documentation/ForLiveExplorers.rst b/Documentation/ForLiveExplorers.rst new file mode 100644 index 00000000..d8ec06cf --- /dev/null +++ b/Documentation/ForLiveExplorers.rst @@ -0,0 +1,52 @@ +.. include:: /Includes.rst.txt + +.. _forLiveExplorers: + +================== +For Live-Explorers +================== + +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 + + 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 diff --git a/Documentation/Introduction.rst b/Documentation/Introduction.rst index 6050b853..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,11 +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 -- 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:`("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: