TASK: Document yaml structure
* To ease contributions and modifications Relates: #54
This commit is contained in:
parent
7c5d95d0e0
commit
74eb4dde20
GPG key ID:
33D6629915560EF4
1 changed files with 96 additions and 7 deletions
|
|
@ -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_<ExtensionName>`` 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...'
|
||||
|
|
|
|||
Loading…
Reference in a new issue