TASK: Document yaml structure

* To ease contributions and modifications

Relates: #54

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_<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...'