TASK: Document yaml structure

* To ease contributions and modifications

Relates: #54
This commit is contained in:
Daniel Siepmann 2017-04-13 15:44:52 +02:00
parent 7c5d95d0e0
commit 74eb4dde20
Signed by: Daniel Siepmann
GPG key ID: 33D6629915560EF4

View file

@ -1,3 +1,4 @@
.. _highlight: yaml
.. _configuration: .. _configuration:
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 project using a :file:`phpcs.xml.dist`. As this is just a PHPCS-Standard, the official documentation
applies. 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 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 already documented by phpcs itself. Therefore this documentation will just mention
:file:`ruleset.xml`. :file:`ruleset.xml`.
@ -22,7 +30,7 @@ The following configuration options are available:
.. _configuration-legacyExtensions: .. _configuration-legacyExtensions:
legacyExtensions legacyExtensions
---------------- ^^^^^^^^^^^^^^^^
Configures which extension names are legacy. Used to provide further checks and warnings about Configures which extension names are legacy. Used to provide further checks and warnings about
possible legacy code. All class usages starting with ``Tx_<ExtensionName>`` where ExtensionName is possible legacy code. All class usages starting with ``Tx_<ExtensionName>`` where ExtensionName is
@ -44,7 +52,7 @@ Example:
.. _configuration-allowedTags: .. _configuration-allowedTags:
allowedTags allowedTags
----------- ^^^^^^^^^^^
Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``. Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``.
@ -66,7 +74,7 @@ Example:
.. _configuration-mappingFile: .. _configuration-mappingFile:
mappingFile mappingFile
----------- ^^^^^^^^^^^
For auto migrating usages of old class names, a PHP file with a mapping is required. The file has to 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`. be in the composer structure :file:`autoload_classaliasmap.php`.
@ -91,7 +99,7 @@ Using ``runtime-set``:
.. _configuration-vendor: .. _configuration-vendor:
vendor vendor
------ ^^^^^^
Used while adding namespaces to legacy class definitions and updating plugin and module 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. registrations. Default is ``YourCompany`` to enable you to search and replace afterwards.
@ -115,7 +123,7 @@ Example:
.. _configuration-removedFunctionConfigFiles: .. _configuration-removedFunctionConfigFiles:
removedFunctionConfigFiles removedFunctionConfigFiles
-------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^
Configure where to look for configuration files defining the removed functions and methods. Default 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 is ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver
@ -138,7 +146,7 @@ Example:
.. _configuration-removedConstantConfigFiles: .. _configuration-removedConstantConfigFiles:
removedConstantConfigFiles removedConstantConfigFiles
-------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^
Configure where to look for configuration files defining the removed constants. Default is 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 ``Configuration/Removed/Functions/*.yaml`` inside the standard itself. We already try to deliver as
@ -160,7 +168,7 @@ Example:
.. _configuration-removedTypoScriptConfigFiles: .. _configuration-removedTypoScriptConfigFiles:
removedTypoScriptConfigFiles removedTypoScriptConfigFiles
---------------------------- ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Configure where to look for configuration files defining the removed TypoScript object identifiers. Configure where to look for configuration files defining the removed TypoScript object identifiers.
Default is ``Configuration/Removed/TypoScript/*.yaml`` inside the standard itself. Default is ``Configuration/Removed/TypoScript/*.yaml`` inside the standard itself.
@ -178,3 +186,84 @@ Example:
.. code:: bash .. code:: bash
--runtime-set removedTypoScriptConfigFiles "/Some/Absolute/Path/*.yaml" --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...'