From 74eb4dde20fe47813a93b089c657559cba8223b1 Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 15:44:52 +0200 Subject: [PATCH] TASK: Document yaml structure * To ease contributions and modifications Relates: #54 --- Documentation/source/configuration.rst | 103 +++++++++++++++++++++++-- 1 file changed, 96 insertions(+), 7 deletions(-) diff --git a/Documentation/source/configuration.rst b/Documentation/source/configuration.rst index cd2812d..106ee94 100644 --- a/Documentation/source/configuration.rst +++ b/Documentation/source/configuration.rst @@ -1,3 +1,4 @@ +.. _highlight: yaml .. _configuration: Configuration @@ -7,6 +8,13 @@ Configuration is done through PHPCS Standards, e.g. provide a custom :file:`rule project using a :file:`phpcs.xml.dist`. As this is just a PHPCS-Standard, the official documentation applies. +Also some configuration is done through yaml files, see :ref:`configuration-yaml-files`. + +.. _configuration-options: + +Options +------- + All options available in :file:`ruleset.xml` are also available in your :file:`phpcs.xml` files, as already documented by phpcs itself. Therefore this documentation will just mention :file:`ruleset.xml`. @@ -22,7 +30,7 @@ The following configuration options are available: .. _configuration-legacyExtensions: legacyExtensions ----------------- +^^^^^^^^^^^^^^^^ Configures which extension names are legacy. Used to provide further checks and warnings about possible legacy code. All class usages starting with ``Tx_`` where ExtensionName is @@ -44,7 +52,7 @@ Example: .. _configuration-allowedTags: allowedTags ------------ +^^^^^^^^^^^ Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``. @@ -66,7 +74,7 @@ Example: .. _configuration-mappingFile: mappingFile ------------ +^^^^^^^^^^^ For auto migrating usages of old class names, a PHP file with a mapping is required. The file has to be in the composer structure :file:`autoload_classaliasmap.php`. @@ -91,7 +99,7 @@ Using ``runtime-set``: .. _configuration-vendor: vendor ------- +^^^^^^ Used while adding namespaces to legacy class definitions and updating plugin and module registrations. Default is ``YourCompany`` to enable you to search and replace afterwards. @@ -115,7 +123,7 @@ Example: .. _configuration-removedFunctionConfigFiles: removedFunctionConfigFiles --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Configure where to look for configuration files defining the removed functions and methods. Default is ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver @@ -138,7 +146,7 @@ Example: .. _configuration-removedConstantConfigFiles: removedConstantConfigFiles --------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^ Configure where to look for configuration files defining the removed constants. Default is ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver as @@ -160,7 +168,7 @@ Example: .. _configuration-removedTypoScriptConfigFiles: removedTypoScriptConfigFiles ----------------------------- +^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Configure where to look for configuration files defining the removed TypoScript object identifiers. Default is ``Configuration/Removed/TypoScript/*.yaml`` inside the standard itself. @@ -178,3 +186,84 @@ Example: .. code:: bash --runtime-set removedTypoScriptConfigFiles "/Some/Absolute/Path/*.yaml" + +.. _configuration-yaml-files: + +YAML Files +---------- + +YAML files are used to configure removed constants, function / methods and TypoScript. We decided to +go with yaml files here, to ease adding stuff in the future. It's a simple format and everyone can +contribute. + +You can configure the paths to look up the files through the specific options, documented above. + +This section will cover the structure of the various yaml files. + +General structure +^^^^^^^^^^^^^^^^^ + +The basic structure is the same for all parts. Inside a file you have to provide an array for each +TYPO3 version:: + + '7.0': + styles.insertContent: + replacement: 'Either remove usage of styles.insertContent or a...' + docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog/7.0...' + '7.1': + \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->includeTCA: + replacement: 'Full TCA is always loaded during bootstrap in ...' + docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog/7...' + +In above example the TypoScript ``styles.insertContent`` was removed in TYPO3 version *7.0*. +Below a TYPO3 version each entry is a removed function or TypoScript part of TYPO3. The key is used +to lookup matchings in the source code. Specific parsing is documented below. + +All entries consists of a ``replacement`` and ``docsUrl`` entry. + +The ``replacement`` can either be ``null`` or a string. If it's null we will show that this part is +removed without any replacement. +If you provide a string, this will be displayed to help during migrations. + +The ``docsUrl`` is displayed in addition, so everyone can take a deeper look at the change, the +effects and how to migrate. + +Also the TYPO3 core team references the forge issues in each change, where you can find the pull +requests. + +Constants and Functions +^^^^^^^^^^^^^^^^^^^^^^^ + +Special parsing is done for the keys identifying removed constants and functions. + +Always provide the fully qualified class namespace. Seperate the constant or method by ``::`` if +it's possible to access it static, otherwise use ``->`` to indicate it's an instance method. + +This is used to check only matching calls. + +Two examples:: + + '7.0': + \TYPO3\CMS\Core\Utility\GeneralUtility::loadTCA: + replacement: null + docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Ch...' + \TYPO3\CMS\Frontend\Controller\TypoScriptFrontendController->includeTCA: + replacement: 'Full TCA is always loaded during bootstrap in FE, th...' + docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Change...' + +TypoScript +^^^^^^^^^^ + +Use ``new`` in front of, to declare the entry as OBJECT, e.g. a cObject. +Only matching types will be checked in source code. + +Two examples:: + + '7.0': + styles.insertContent: + replacement: 'Either remove usage of styles.insertContent or add a sni...' + docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog...' + '7.1': + new HRULER: + replacement: 'Any installation should migrate to alternatives such as F...' + docsUrl: 'https://docs.typo3.org/typo3cms/extensions/core/7.6/Changelog...'