diff --git a/.editorconfig b/.editorconfig index 0c5bdfe..9d5e9dc 100644 --- a/.editorconfig +++ b/.editorconfig @@ -23,7 +23,7 @@ indent_style = tab indent_size = 2 # ReST files -[*.rst] +[{*.rst,*.rst.txt}] indent_size = 3 max_line_length = 80 diff --git a/Documentation/ContinuousIntegration.rst b/Documentation/ContinuousIntegration.rst new file mode 100644 index 0000000..1bc5e73 --- /dev/null +++ b/Documentation/ContinuousIntegration.rst @@ -0,0 +1,46 @@ +.. include:: /Includes.rst.txt + +.. _continuous-integration: + +====================== +Continuous integration +====================== + +As an example, this extension provides several ways to perform the code quality +checks and tests in a CI pipeline. You can copy the +appropriate configuration depending on which Git hosting service and CI +platform you want to use. + +.. contents:: Table of Contents: + :backlinks: top + :class: compact-list + :depth: 2 + :local: + +.. _github-actions: + +GitHub Actions +============== + +This extension has two code-checking workflows for +`GitHub Actions `__: + +- `one that uses the local tools `__: + This is the workflow you most probably would want to use: + This workflow uses the development tools installed via Composer and PHIVE and + calls them using the provided Composer scripts. Use this workflow if you want + to run the code quality checks locally as well as in GitHub Actions. + +- `one that completely relies on predefined actions `__: + This workflow does not need the development tools to be installed locally. + Use this workflow if you only want to run the code quality checks in GitHub + Actions, but not locally. + +.. _gitlab-ci: + +GitLab CI +========= + +This extension also provides +`configuration `__ +for `GitLab CI `__. diff --git a/Documentation/DependencyManager.rst b/Documentation/DependencyManager.rst new file mode 100644 index 0000000..e7bcdb8 --- /dev/null +++ b/Documentation/DependencyManager.rst @@ -0,0 +1,21 @@ +.. include:: /Includes.rst.txt + +.. _dependency-manager: + +================== +Dependency manager +================== + +To keep things simple, most development tools, for example PHP_CodeSniffer, are +installed by Composer as development requirements and in some cases where +installation via Composer is not possible, we use `PHIVE `__. + +PHIVE packages each tool with all its dependencies as +a separate PHAR. This helps avoid dependency hell (which means that you cannot +install or upgrade some tool as the tool's dependencies conflict with the +dependencies on another library). It also allows running versions of tools +that require a PHP version that is higher than the lowest allowed PHP version +for this project. Currently, we use PHIVE for +`PHP Copy/Paste Detector `__, +that requires PHP >= 7.3, which conflicts with this project's PHP version +support (we also support PHP 7.2). diff --git a/Documentation/Documentation.rst b/Documentation/Documentation.rst new file mode 100644 index 0000000..793e82f --- /dev/null +++ b/Documentation/Documentation.rst @@ -0,0 +1,22 @@ +.. include:: /Includes.rst.txt + +.. _documentation: + +======================= +Documentation rendering +======================= + +In order to render the documentation, this extension provides a Composer script +that you can run locally via + +.. index:: Commands; composer docs:generate +.. code-block:: bash + + composer docs:generate + +You do not need to start or build the containers for this as this happens +automatically. + +.. seealso:: + + For further details read the :doc:`TYPO3 Documentation Rendering Guide `. diff --git a/Documentation/Documentation/Rendering/Index.rst b/Documentation/Documentation/Rendering/Index.rst deleted file mode 100644 index 32db46b..0000000 --- a/Documentation/Documentation/Rendering/Index.rst +++ /dev/null @@ -1,26 +0,0 @@ -.. include:: ../../Includes.txt - -.. _documentation: - -======================= -Documentation rendering -======================= - -.. _how-to-render-documentation-locally: - -How to render documentation locally? -==================================== - -In order to render documentation, first of all, clone the repository: - -.. code-block:: bash - - git clone https://github.com/TYPO3-Documentation/tea.git - -then go to the extension root: - -.. code-block:: bash - - cd tea - -and follow `the TYPO3 documentation quickstart guide `_ diff --git a/Documentation/Environment.rst b/Documentation/Environment.rst new file mode 100644 index 0000000..a948522 --- /dev/null +++ b/Documentation/Environment.rst @@ -0,0 +1,11 @@ +.. include:: /Includes.rst.txt + +.. _development-environment: + +======================= +Development environment +======================= + +You can either run the code quality checks and automated tests locally (using a +local PHP, Composer, and database), or you can use +`ddev `__ for a Docker-based setup. diff --git a/Documentation/Images/SlidesCover.jpg b/Documentation/Images/SlidesCover.jpg new file mode 100644 index 0000000..20e51e2 Binary files /dev/null and b/Documentation/Images/SlidesCover.jpg differ diff --git a/Documentation/Images/VideoCover.jpg b/Documentation/Images/VideoCover.jpg new file mode 100644 index 0000000..1b029a4 Binary files /dev/null and b/Documentation/Images/VideoCover.jpg differ diff --git a/Documentation/Includes.rst.txt b/Documentation/Includes.rst.txt new file mode 100644 index 0000000..1f85da4 --- /dev/null +++ b/Documentation/Includes.rst.txt @@ -0,0 +1,34 @@ +.. More information about this file: + https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#includes-rst-txt + +.. ---------- +.. text roles +.. ---------- + +.. role:: aspect(emphasis) +.. role:: bash(code) +.. role:: html(code) +.. role:: js(code) +.. role:: php(code) +.. role:: rst(code) +.. role:: sep(strong) +.. role:: sql(code) + +.. role:: tsconfig(code) + :class: typoscript + +.. role:: typoscript(code) +.. role:: xml(code) + :class: html + +.. role:: yaml(code) + +.. default-role:: code + +.. --------- +.. highlight +.. --------- + +.. By default, code blocks use automatically detected syntax highlighting + +.. highlight:: guess diff --git a/Documentation/Includes.txt b/Documentation/Includes.txt deleted file mode 100644 index b9256d4..0000000 --- a/Documentation/Includes.txt +++ /dev/null @@ -1,17 +0,0 @@ -.. ================================================== -.. FOR YOUR INFORMATION -.. -------------------------------------------------- -.. -*- coding: utf-8 -*- with BOM. - -.. This is 'Includes.txt'. It is included at the very top of each and - every ReST source file in THIS documentation project (= manual). - -.. role:: html(code) -.. role:: typoscript(code) -.. role:: ts(typoscript) - :class: typoscript -.. role:: php(code) -.. role:: yaml(code) - -.. default-role:: code -.. highlight:: guess diff --git a/Documentation/Index.rst b/Documentation/Index.rst index 99aba74..55746e9 100644 --- a/Documentation/Index.rst +++ b/Documentation/Index.rst @@ -1,10 +1,16 @@ -.. include:: Includes.txt +.. include:: /Includes.rst.txt .. _start: -============================================================= -EXT:tea -============================================================= +======================= +TYPO3 extension ``tea`` +======================= + +:Extension key: + tea + +:Package name: + ttn/tea :Version: |release| @@ -12,52 +18,43 @@ EXT:tea :Language: en -:Description: - This TYPO3 extension is an example of best practices in continuous integration and automated code checks, also - Extbase/Fluid-based extensions for TYPO3 CMS using PHPUnit, writing unit and functional tests for - extensions for TYPO3 CMS using PHPUnit. - -:Keywords: - tea, ci, continousintegration, gitlab, githubactions, actions, tests, functional, unit - -:Copyright: - 2022 by TYPO3 Association - -:Authors: - * Oliver Klee - -:Email: - typo3-coding@oliverklee.de +:Author: + Oliver Klee & Contributors :License: This extension is published under the - `GNU General Public License v2.0 `__ + `GNU General Public License v2.0 `__. :Rendered: - |today| + |today| -TYPO3 -===== +---- -The content of this document is related to TYPO3 CMS, -a GNU/GPL CMS/Framework available from `typo3.org `_ . +This TYPO3 extension, based on Extbase and Fluid, is an example of best +practices in automated code checks, unit/functional/acceptance testing and +continuous integration. -For Contributors -================ +---- -You are welcome to help improve this guide if you missing something. -Just click on "Edit me on GitHub" on the top right to submit your change request -or `report a problem `__ - -Table of Contents -================= +**Table of Contents:** .. toctree:: - :maxdepth: 5 + :maxdepth: 2 :titlesonly: - :glob: - Introduction/Index - Linters/Index - Documentation/Rendering/Index + Introduction + TestingFramework + Environment + DependencyManager + Running + ContinuousIntegration + Documentation + Security + +.. Meta Menu + +.. toctree:: + :hidden: + Sitemap + genindex diff --git a/Documentation/Introduction.rst b/Documentation/Introduction.rst new file mode 100644 index 0000000..6d05091 --- /dev/null +++ b/Documentation/Introduction.rst @@ -0,0 +1,53 @@ +.. include:: /Includes.rst.txt + +.. _introduction: + +============ +Introduction +============ + +.. _what-it-does: + +What does it do? +================ + +This TYPO3 extension, based on Extbase and Fluid, is an example of best +practices in automated code checks, unit/functional/acceptance testing and +continuous integration (CI). + +.. _presentation-online-days-2021: + +Presentation at the TYPO3 Online Days 2021 +========================================== + +At the TYPO3 Online Days 2021, `Oliver Klee `__ +held a session presenting our approach to automate extension code quality. +Have a look at the slides and the video of the presentation! + +.. container:: row m-0 p-0 + + .. container:: col-md-6 pl-0 pr-3 py-3 m-0 + + .. container:: card px-0 h-100 + + .. rst-class:: card-header h3 + + .. rubric:: Slides + + .. container:: card-body + + .. image:: /Images/SlidesCover.jpg + :target: https://speakerdeck.com/oliverklee/automating-the-code-quality-of-your-extensions + + .. container:: col-md-6 pl-0 pr-3 py-3 m-0 + + .. container:: card px-0 h-100 + + .. rst-class:: card-header h3 + + .. rubric:: Video + + .. container:: card-body + + .. image:: /Images/VideoCover.jpg + :target: https://youtu.be/_oe8ku2GM84?t=6983 diff --git a/Documentation/Introduction/Index.rst b/Documentation/Introduction/Index.rst deleted file mode 100644 index 0df1e6d..0000000 --- a/Documentation/Introduction/Index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. include:: ../Includes.txt - -.. _introduction: - -============== -Introduction -============== - -.. _what-it-does: - -What does it do? -================ - -This TYPO3 extension is an example of best practices in continuous integration and automated code checks, also -writing unit and functional tests with PHPUnit in Extbase/Fluid-based extensions for TYPO3 CMS, and then running them -in a pipeline. diff --git a/Documentation/Linters/GitHub/Index.rst b/Documentation/Linters/GitHub/Index.rst deleted file mode 100644 index b4334dd..0000000 --- a/Documentation/Linters/GitHub/Index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. include:: ../../Includes.txt - -.. _linters_github: - -======================= -Running lints in GitHub -======================= - -For GitHub, we prepared two ways of running lints. First one relies on executing -composer scripts, and second is using exported, prepared GitHub Actions in your -workflow. - -Composer scripts -================ -You can run your lints using composer scripts. An example workflow is defined in -`ci-composer-scripts.yml`. - -Ready to use GitHub Actions -=========================== -You can use prepared GitHub Actions. All of ready to use GitHub Actions are in -`TYPO3 Continuous Integration organisation `_ -An example workflow is defined in `ci.yml`. diff --git a/Documentation/Linters/GitLab/Index.rst b/Documentation/Linters/GitLab/Index.rst deleted file mode 100644 index 1c5f6fb..0000000 --- a/Documentation/Linters/GitLab/Index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. include:: ../../Includes.txt - -.. _linters_gitlab: - -======================= -Running lints in GitLab -======================= -In GitLab CI you should use composer scripts. - -Composer scripts -================ -You can run your lints using composer scripts. An example workflow is defined in -`.gitlab-ci.yml`. diff --git a/Documentation/Linters/Index.rst b/Documentation/Linters/Index.rst deleted file mode 100644 index f721b8f..0000000 --- a/Documentation/Linters/Index.rst +++ /dev/null @@ -1,18 +0,0 @@ -.. include:: ../Includes.txt - -.. _linters: - -======================= -Linters -======================= - -.. only:: html - - This chapter describes how to use linters in CI. - -.. toctree:: - :maxdepth: 5 - :titlesonly: - - GitHub/Index - GitLab/Index diff --git a/Documentation/Running.rst b/Documentation/Running.rst new file mode 100644 index 0000000..12eb4ee --- /dev/null +++ b/Documentation/Running.rst @@ -0,0 +1,281 @@ +.. include:: /Includes.rst.txt + +.. _running-checks-and-tests: + +====================== +Running checks & tests +====================== + +Most code checks and tests can be run via Composer commands. + +.. contents:: Table of Contents: + :backlinks: top + :class: compact-list + :depth: 1 + :local: + +.. _composer-scripts: + +Composer scripts +================ + +For most development-related tasks, this extension provides Composer scripts. +If you are working locally, you can run them using :bash:`composer `. +If you are working with ddev, you can run them with :bash:`ddev composer `. +You do not need to start or build the containers for this as this happens +automatically. + +The code-quality-related Composer scripts make use of the PHIVE-installed tools. +This means that for non-ddev-based development, you need to run :bash:`phive install` +before you can use the Composer scripts. + +You can run :bash:`composer` (or :bash:`ddev composer`) to display a list of all available +Composer commands and scripts. For all custom Composer scripts there are descriptions +in the `script-description` section of the `composer.json`. + +.. _running-code-checks: + +Running code checks +=================== + +You can currently run these code checks on the command line (if working locally without ddev, omit the :bash:`ddev` part): + +.. index:: Commands; composer ci +.. code-block:: bash + + ddev composer ci + +Runs all dynamic and static code checks. + +.. index:: Commands; composer ci:composer:normalize +.. code-block:: bash + + ddev composer ci:composer:normalize + +Checks the composer.json. + +.. index:: Commands; composer ci:json:lint +.. code-block:: bash + + ddev composer ci:json:lint + +Lints the JSON files. + +.. index:: Commands; composer ci:php +.. code-block:: bash + + ddev composer ci:php + +Runs all static checks for the PHP files. + +.. index:: Commands; composer ci:php:copypaste +.. code-block:: bash + + ddev composer ci:php:copypaste + +Checks for copy\'n\'pasted PHP code. + +.. index:: Commands; composer ci:php:cs-fixer +.. code-block:: bash + + ddev composer ci:php:cs-fixer + +Checks the code style with the PHP Coding Standards Fixer (PHP-CS-Fixer). + +.. index:: Commands; composer ci:php:lint +.. code-block:: bash + + ddev composer ci:php:lint + +Lints the PHP files for syntax errors. + +.. index:: Commands; composer ci:php:sniff +.. code-block:: bash + + ddev composer ci:php:sniff + +Checks the code style with PHP_CodeSniffer (PHPCS). + +.. index:: Commands; composer ci:php:stan +.. code-block:: bash + + ddev composer ci:php:stan + +Checks the PHP types using PHPStan. + +.. index:: Commands; composer ci:static +.. code-block:: bash + + ddev composer ci:static + +Runs all static code checks (syntax, style, types). + +.. index:: Commands; composer ci:ts:lint +.. code-block:: bash + + ddev composer ci:ts:lint + +Lints the TypoScript files. + +.. index:: Commands; composer ci:yaml:lint +.. code-block:: bash + + ddev composer ci:yaml:lint + +Lints the YAML files. + +.. index:: Commands; composer fix:php +.. code-block:: bash + + ddev composer fix:php + +Runs all fixers for the PHP code. + +.. index:: Commands; composer fix:php:cs +.. code-block:: bash + + ddev composer fix:php:cs + +Fixes the code style with PHP-CS-Fixer. + +.. index:: Commands; composer fix:php:sniff +.. code-block:: bash + + ddev composer fix:php:sniff + +Fixes the code style with PHP_CodeSniffer. + +.. index:: Commands; composer phpstan:baseline +.. code-block:: bash + + ddev composer phpstan:baseline + +Updates the PHPStan baseline file to match the code. + +.. _running-unit-and-functional-tests: + +Running unit and functional tests +================================= + +You can currently run these tests and coverages on the command line (if working locally without ddev, omit the :bash:`ddev` part): + +.. index:: Commands; composer ci:coverage +.. code-block:: bash + + ddev composer ci:coverage + +Runs the ci:coverage script as defined in composer.json. + +.. index:: Commands; composer ci:coverage:functional +.. code-block:: bash + + ddev composer ci:coverage:functional + +Generates the code coverage report for functional tests. + +.. index:: Commands; composer ci:coverage:merge +.. code-block:: bash + + ddev composer ci:coverage:merge + +Merges the code coverage reports for unit and functional tests. + +.. index:: Commands; composer ci:coverage:unit +.. code-block:: bash + + ddev composer ci:coverage:unit + +Generates the code coverage report for unit tests. + +.. index:: Commands; composer ci:dynamic +.. code-block:: bash + + ddev composer ci:dynamic + +Runs all PHPUnit tests (unit and functional). + +.. index:: Commands; composer ci:tests +.. code-block:: bash + + ddev composer ci:tests + +Runs all PHPUnit tests (unit and functional). + +.. index:: Commands; composer ci:tests:functional +.. code-block:: bash + + ddev composer ci:tests:functional + +Runs the functional tests. + +.. index:: Commands; composer ci:tests:unit +.. code-block:: bash + + ddev composer ci:tests:unit + +Runs the unit tests. + +.. _running-unit-and-functional-tests-in-phpstorm: + +Running unit and functional tests in PHPStorm +============================================= + +General setup +------------- + +- Open :guilabel:`File > Settings > PHP > Test Frameworks`. +- (*) Use Composer autoloader. +- Path to script: select `.Build/vendor/autoload.php` in your project folder. + +In the Run configurations, edit the PHPUnit configuration and use these +settings so this configuration can serve as a template: + +- Directory: use the `Tests/Unit` directory in your project. +- (*) Use alternative configuration file. +- Use `.Build/vendor/typo3/testing-framework/Resources/Core/Build/UnitTests.xml` + in your project folder. +- Add the following environment variables: + + - typo3DatabaseUsername + - typo3DatabasePassword + - typo3DatabaseHost + - typo3DatabaseName + +Unit tests configuration +------------------------ + +In the Run configurations, copy the PHPUnit configuration and use these +settings: + +- Directory: use the `Tests/Unit` directory in your project + +Functional tests configuration +------------------------------ + +In the Run configurations, copy the PHPUnit configuration and use these +settings: + +- Directory: use the `Tests/Functional` directory in your project. +- (*) Use alternative configuration file. +- Use + `.Build/vendor/typo3/testing-framework/Resources/Core/Build/FunctionalTests.xml`. + +.. _running-acceptance-tests: + +Running acceptance tests +======================== + +1. Make sure you have Chrome installed on your machine. +2. `Download the latest version of ChromeDriver `__. +3. Unzip it. +4. Execute `chromedriver --url-base=wd/hub`. +5. In another terminal, run `.Build/vendor/bin/codecept run`. + +.. _running-acceptance-tests-in-phpstorm: + +Running acceptance tests in PhpStorm +==================================== + +1. Make sure the "Codeception Framework" plugin is activated. +2. Right-click on `Tests/Acceptance/StarterCest.php`. +3. Run 'Acceptance (Codeception)'. diff --git a/Documentation/Security.rst b/Documentation/Security.rst new file mode 100644 index 0000000..8760ea9 --- /dev/null +++ b/Documentation/Security.rst @@ -0,0 +1,16 @@ +.. include:: /Includes.rst.txt + +.. _security: + +======== +Security +======== + +Libraries and extensions do not need the security check as they should not have +any restrictions concerning the other libraries they are installed alongside +with (unless those would create breakage). Libraries and extension also should +not have a version-controlled `composer.lock` (which usually is used for +security checks). + +Instead, the projects and distributions (i.e., for TYPO3 installations) need to +have the security checks. diff --git a/Documentation/Settings.cfg b/Documentation/Settings.cfg index dac93f2..0fa8cdc 100644 --- a/Documentation/Settings.cfg +++ b/Documentation/Settings.cfg @@ -1,66 +1,62 @@ +# More information about this file: +# https://docs.typo3.org/m/typo3/docs-how-to-document/main/en-us/GeneralConventions/FileStructure.html#settings-cfg + [general] -# ................................................................................. -# ... (required) title (displayed in left sidebar (desktop) or top panel (mobile) -# ................................................................................. -project = TYPO3 EXT:tea - -# ................................................................................. -# ... (recommended) version, displayed next to title (desktop) and in `__ +can support multiple TYPO3 versions at a time, and +it provides version-independent abstractions for testing, making it the perfect +companion for this approach. + +This is the approach that we have chosen for this extension as we do not want +to maintain two branches in parallel. + +.. _testing-framework-approach-one-version: + +Approach 2: One branch per TYPO3 LTS version +============================================ + +With this approach, there are two main branches that get new features in +parallel. Each branch supports exactly one TYPO3 LTS version. + +The upside is that this slightly decreases code complexity as +version-dependent code switches are not necessary. The downside is that there +are two branches to maintain, which makes adding new features (and all other +code changes) more of a hassle. + +For this approach, the +`TYPO3 testing framework `__ +- which supports only one TYPO3 LTS version at a time - will work just fine. + diff --git a/Documentation/genindex.rst b/Documentation/genindex.rst new file mode 100644 index 0000000..806ec56 --- /dev/null +++ b/Documentation/genindex.rst @@ -0,0 +1,7 @@ +.. include:: /Includes.rst.txt + +===== +Index +===== + +.. Sphinx will insert here the general index automatically. diff --git a/README.md b/README.md index d7a48aa..11a1a27 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,29 @@ # Example TYPO3 extension for code quality checks and automated tests +[![Latest stable version](https://poser.pugx.org/ttn/tea/v/stable.svg)](https://packagist.org/packages/ttn/tea) +[![Total downloads](https://poser.pugx.org/ttn/tea/downloads.svg)](https://packagist.org/packages/ttn/tea) +[![Monthly Downloads](https://poser.pugx.org/ttn/tea/d/monthly)](https://packagist.org/packages/ttn/tea) +[![TYPO3 V10](https://img.shields.io/badge/TYPO3-10-orange.svg)](https://get.typo3.org/version/10) +[![TYPO3 V11](https://img.shields.io/badge/TYPO3-11-orange.svg)](https://get.typo3.org/version/11) [![GitHub CI status](https://github.com/TYPO3-Documentation/tea/workflows/CI/badge.svg?branch=main)](https://github.com/TYPO3-Documentation/tea/actions) [![GitLab CI status](https://gitlab.typo3.org/qa/example-extension/badges/main/pipeline.svg)](https://gitlab.typo3.org/qa/example-extension/-/pipelines) -[![Latest stable version](https://poser.pugx.org/ttn/tea/v/stable.svg)](https://packagist.org/packages/ttn/tea) -[![TYPO3](https://img.shields.io/badge/TYPO3-10-orange.svg)](https://get.typo3.org/version/10) -[![TYPO3](https://img.shields.io/badge/TYPO3-11-orange.svg)](https://get.typo3.org/version) [![Code Coverage Badge](https://github.com/TYPO3-Documentation/tea/blob/code-coverage-badge/badge.svg)](https://github.com/TYPO3-Documentation/tea/blob/code-coverage-badge/clover.xml) [![Total downloads](https://poser.pugx.org/ttn/tea/downloads.svg)](https://packagist.org/packages/ttn/tea) [![License](https://poser.pugx.org/ttn/tea/license.svg)](https://packagist.org/packages/ttn/tea) [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa.svg)](CODE_OF_CONDUCT.md) -## What is this all about? - -This Extbase/Fluid-based TYPO3 extension is an example showcase for best -practices in continuous integration, automated code checks and unit and -functional testing. +This TYPO3 extension, based on Extbase and Fluid, is an example of best +practices in automated code checks, unit/functional/acceptance testing and +continuous integration. You can also use this extension to manage your collection of delicious teas. +| | URL | +|------------------|----------------------------------------------| +| **Repository:** | https://github.com/TYPO3-Documentation/tea | +| **Read online:** | https://docs.typo3.org/p/ttn/tea/main/en-us/ | +| **TER:** | https://extensions.typo3.org/extension/tea/ | + ## Presentation at the TYPO3 Online Days 2021 At the TYPO3 Online Days 2021, [Oliver Klee](https://www.oliverklee.de/) held a @@ -31,209 +37,3 @@ extensions. ### Video recording [![video still](https://img.youtube.com/vi/_oe8ku2GM84/0.jpg)](https://youtu.be/_oe8ku2GM84?t=6983) - -## Extension manual - -The rendered extension manual is available -[on docs.typo3.org](https://docs.typo3.org/p/ttn/tea/master/en-us/). - -## Used testing framework and approach to TYPO3 version support - -Extensions usually needs to support two LTS versions of TYPO3 in parallel -(assuming that they should support all currently supported TYPO3 LTS versions). -To achieve this, there are two different approaches, which also affect the -choice of a testing framework for unit and functional tests: - -### Approach 1: single branch with multi-version support - -With this approach, there is one main branch that gets new features. It needs to -support two TYPO3 LTS versions in parallel. - -The downside is that this slightly increases code complexity (as -version-dependent code switches might be necessary). The upside is that there -is only one branch to maintain, which makes adding new features (and all other -code changes) a lot less of a hassle. - -As the [TYPO3 testing framework](https://github.com/TYPO3/testing-framework) -supports only one TYPO3 LTS version at a time, you will need to use the -[Nimut testing framework](https://github.com/Nimut/testing-framework) instead. -This testing framework can support multiple TYPO3 versions at a time, and -it provides version-independent abstractions for testing. - -(This is the approach that we have chosen for this extension as we do not want -to maintain two branches in parallel.) - -### Approach 2: multiple branches for each TYPO3 version - -With this approach, there is are two main branches that get new features in -parallel. Each branch supports exactly one TYPO3 LTS version. - -The upside is that this slightly decreases code complexity (as -version-dependent code switches are not necessary). The downside is that there -are two branches to maintain, which makes adding new features (and all other -code changes) more of a hassle. - -For this approach, the -[TYPO3 testing framework](https://github.com/TYPO3/testing-framework) (which -supports only one TYPO3 LTS version at a time) will work just fine. - -## Working locally or Docker-based with ddev - -You can run the automated tests and code quality checks either locally (with a -local PHP, Composer and database), or you can use -[ddev](https://github.com/drud/ddev) for a Docker-based setup. - -## Composer, PHIVE, GitHub Actions and GitLab CI - -### Development tools: Composer, PHIVE and dependency hell - -To keep things simple, most development tools (e.g., PHP_CodeSniffer) are -installed as development Composer dependencies. - -For cases where an installation via Composer is not possible, we are using -[PHIVE](https://phar.io/). PHIVE packages each tool with all its dependencies as -a separate PHAR. This helps avoid dependency hell (which means that you cannot -install or upgrade some tool as the tool's dependencies conflict with the -dependencies on another library). It also allows running versions of tools -that require a PHP version that is higher than the lowest allowed PHP version -for this project. - -Currently, this is the case for -[PHP Copy/Paste Detector (PHPCPD)](https://github.com/sebastianbergmann/phpcpd), -which requires PHP >= 7.3, which conflicts with this project's PHP version -support (we also support PHP 7.2). - -### Running the code quality checks locally and in a CI environment - -As an example, this extension provides several redundant ways to run the code -quality checks. (Running the unit and functional tests is a bit different.) -You can copy the corresponding configuration depending on which Git hosting -service and which CI platform you plan to use and whether you would like to run -the code quality checks locally: - -#### GitHub Actions - -This extension has two code-checking workflows for -[GitHub Actions](https://github.com/TYPO3-Documentation/tea/actions): - -- [one that uses the local tools](.github/workflows/ci.yml): - This is the workflow you most probably would want to use: - This workflow uses the development tools installed via Composer and PHIVE and - calls them using the provided Composer scripts. Use this workflow if you want - to run the code quality checks locally as well as in GitHub Actions. - -- [one that completely relies on predefined actions](.github/workflows/predefined.yml): - This workflow does not need the development tools to be installed locally. - Use this workflow if you only want to run the code quality checks in GitHub - Actions, but not locally. - -#### GitLab CI - -This extension also provides [configuration](.gitlab/pipeline/.gitlab-ci.yml) -for [GitLab CI](https://gitlab.typo3.org/qa/example-extension/-/pipelines). - -## Composer scripts - -For most development-related tasks, this extension provides Composer scripts. -If you are working locally, you can run them using `composer `. If -you are working with ddev, you can run them with `ddev composer `. -(You do not need to start or build the containers for this as this happens -automatically.) - -The code-quality-related Composer scripts make use of the PHIVE-installed tools. -This means that for non-ddev-based development, you need to run `phive install` -before you can use the Composer scripts. - -### Available Composer scripts - -You can run `composer` (or `ddev composer`) to display a list of all available -Composer commands and scripts. (For all custom Composer scripts, are descriptions -in the `composer.json` in the `script-description` section.) - -## Running the unit and functional tests - -### On the command line - -To run the unit tests with ddev, use this command: - -```bash -ddev composer ci:tests:unit -``` -To run the functional tests with ddev, use this command: - -```bash -ddev composer ci:tests:functional -``` - -If you are working locally without ddev, omit the `ddev` part. - -### In PhpStorm - -#### General setup for PHPUnit - -File > Settings > PHP > Test Frameworks - -- (*) Use Composer autoloader -- Path to script: select `.Build/vendor/autoload.php` in your project folder - -In the Run configurations, edit the PHPUnit configuration and use these -settings so this configuration can serve as a template: - -- Directory: use the `Tests/Unit` directory in your project -- (*) Use alternative configuration file -- use `.Build/vendor/typo3/testing-framework/Resources/Core/Build/UnitTests.xml` - in your project folder -- add the following environment variables: - - typo3DatabaseUsername - - typo3DatabasePassword - - typo3DatabaseHost - - typo3DatabaseName - -#### Unit tests configuration - -In the Run configurations, copy the PHPUnit configuration and use these -settings: - -- Directory: use the `Tests/Unit` directory in your project - -#### Functional tests configuration - -In the Run configurations, copy the PHPUnit configuration and use these -settings: - -- Directory: use the `Tests/Functional` directory in your project -- (*) Use alternative configuration file -- use - `.Build/vendor/typo3/testing-framework/Resources/Core/Build/FunctionalTests.xml` - -## Running the acceptance tests - -### On the command line - -1. make sure you have Chrome installed on your machine -1. [download the latest version of ChromeDriver](http://chromedriver.chromium.org/downloads) -1. unzip it -1. `chromedriver --url-base=wd/hub` -1. `.Build/vendor/bin/codecept run` (in another terminal) - -### In PhpStorm - -1. make sure the "Codeception Framework" plugin is activated -2. right-click on `Tests/Acceptance/StarterCest.php` -3. Run 'Acceptance (Codeception)' - -## Security - -Libraries and extensions do not need the security check as they should not have -any restrictions concerning the other libraries they are installed alongside -with (unless those would create breakage). Libraries and extension also should -not have a version-controlled `composer.lock` (which usually is used for -security checks). - -Instead, the projects and distributions (i.e., for TYPO3 installations) need to -have the security checks. - -## Rendering the documentation - -After you have cloned the git repository, follow -[the TYPO3 documentation quickstart guide](https://docs.typo3.org/m/typo3/docs-how-to-document/master/en-us/RenderingDocs/Quickstart.html). diff --git a/composer.json b/composer.json index 5dbc408..858e72f 100644 --- a/composer.json +++ b/composer.json @@ -20,9 +20,11 @@ "role": "developer" } ], + "homepage": "https://extensions.typo3.org/extension/tea/", "support": { "issues": "https://github.com/TYPO3-Documentation/tea/issues", - "source": "https://github.com/TYPO3-Documentation/tea" + "source": "https://github.com/TYPO3-Documentation/tea", + "docs": "https://docs.typo3.org/p/ttn/tea/main/en-us/" }, "require": { "php": "~7.2.0 || ~7.3.0 || ~7.4.0 || ~8.0 || ~8.1",