From 8cb68ff6bb4e75301154ca461bd7f39433ade62a Mon Sep 17 00:00:00 2001 From: Daniel Siepmann Date: Thu, 13 Apr 2017 10:54:32 +0200 Subject: [PATCH] TASK: Migrate / write documentation * Add further information and sections, e.g. about contribution and extending. Relates: #63 --- Documentation/source/conf.py | 26 ++++- Documentation/source/configuration.rst | 154 +++++++++++++++++++++++++ Documentation/source/contribution.rst | 36 ++++++ Documentation/source/extending.rst | 94 +++++++++++++++ Documentation/source/features.rst | 110 ++++++++++++++++++ Documentation/source/index.rst | 79 ++++++++++--- Documentation/source/usage.rst | 45 ++++++++ 7 files changed, 525 insertions(+), 19 deletions(-) create mode 100644 Documentation/source/configuration.rst create mode 100644 Documentation/source/contribution.rst create mode 100644 Documentation/source/extending.rst create mode 100644 Documentation/source/features.rst create mode 100644 Documentation/source/usage.rst diff --git a/Documentation/source/conf.py b/Documentation/source/conf.py index 709fc0e..406a886 100644 --- a/Documentation/source/conf.py +++ b/Documentation/source/conf.py @@ -109,9 +109,23 @@ todo_include_todos = True # -- Options for HTML output ---------------------------------------------- +import guzzle_sphinx_theme + +html_theme_path = guzzle_sphinx_theme.html_theme_path() +html_theme = 'guzzle_sphinx_theme' + +# Register the theme as an extension to generate a sitemap.xml +extensions.append("guzzle_sphinx_theme") + +# Guzzle theme options (see theme.conf for more information) +# html_theme_options = { +# # Set the name of the project to appear in the sidebar +# "project_nav_name": project, +# } + # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'alabaster' +# html_theme = 'alabaster' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the @@ -123,7 +137,7 @@ html_theme = 'alabaster' # The name for this set of Sphinx documents. # " v documentation" by default. -#html_title = u'Automated TYPO3 Update v0.1.0' +html_title = u'Automated TYPO3 Update v0.1.0' # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -157,7 +171,13 @@ html_static_path = ['_static'] #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = { + '**': ['logo-text.html', + 'globaltoc.html', + 'localtoc.html', + 'searchbox.html', + ], +} # Additional templates that should be rendered to pages, maps page names to # template names. diff --git a/Documentation/source/configuration.rst b/Documentation/source/configuration.rst new file mode 100644 index 0000000..07023b2 --- /dev/null +++ b/Documentation/source/configuration.rst @@ -0,0 +1,154 @@ +.. _configuration: + +Configuration +============= + +Configuration is done through PHPCS Standards, e.g. provide a custom :file:`ruleset.xml` or inside your +project using a :file:`phpcs.xml.dist`. As this is just a PHPCS-Standard, the official documentation +applies. + +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`. + +Beside that, some options are also available through CLI. Examples are always provided. + +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 +defined in this array, will produce a warning, until the class is already found to be deprecaed. + +Can and have to be configured for each sniff, e.g. ``Instanceof`` and ``DocComment``. + +Example: + +.. code:: xml + + + + + + + + +.. _configuration-allowedTags: + +allowedTags +----------- + +Only used inside Sniff ``Typo3Update.LegacyClassnames.DocComment``. + +Configures which tags are checked for legacy class names. + +This way you can add checks for further tags you are using. All strings inside the tag are checked, +so no matter where the class name occurs inside the tag. + +Example: + +.. code:: xml + + + + + + + +.. _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`. +If TYPO3 is already installed using composer, you can use this file through configuration, or by +copying to the default location, which is :file:`LegacyClassnames.php` in the root of this project. + +Configure where the `LegacyClassnames.php` is located, through ``ruleset.xml`` or using +``--runtime-set``. Default is `LegacyClassnames.php` in the project root. + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Using ``runtime-set``: + +.. code:: bash + + --runtime-set mappingFile /projects/typo3_installation/vendor/composer/autoload_classaliasmap.php + +.. _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. + +If you use multiple vendors through your projects, use the cli to define the vendor and run +``phpcbf`` over specific folders, this way you can update your project step by step with different +vendors. + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Example: + +.. code:: bash + + --runtime-set vendor YourVendor + +.. _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 +as much as possible. +Globing is used, so placeholders like ``*`` are possible, see +https://secure.php.net/manual/en/function.glob.php + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Example: + +.. code:: bash + + --runtime-set removedFunctionConfigFiles "/Some/Absolute/Path/*.yaml" + +.. _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 +much as possible. Globing is used, so placeholders like ``*`` are possible, see +https://secure.php.net/manual/en/function.glob.php + +Using :file:`ruleset.xml`: + +.. code:: xml + + + +Example: + +.. code:: bash + + --runtime-set removedConstantConfigFiles "/Some/Absolute/Path/*.yaml" diff --git a/Documentation/source/contribution.rst b/Documentation/source/contribution.rst new file mode 100644 index 0000000..7a0ad9d --- /dev/null +++ b/Documentation/source/contribution.rst @@ -0,0 +1,36 @@ +.. _highlight: bash + +Contribution +============ + +The project is hosted at https://git.higidi.com/Automated-TYPO3-Update/automated-typo3-update fill +issues there. Also you can fork and clone the project there and provide merge requests. + +Also you can contact us on `TYPO3 slack`_. + +Documentation +------------- + +Documentation is written using `reStructuredText`_ ans `sphinx`_. + +Just open the files with a text editor and update contents. + +To render documentation locally install `docker`_ and run:: + + docker run -v "$PWD/Documentation":/sphinx danielsiepmann/sphinx + +from within the project root. + +Code +---- + +A :file:`.editorconfig` is already provided to setup your editor. Also `phpcs` is configured, so +make sure to check your coding style with `phpcs`_. + +New sniffs have to be covered by tests, see :ref:`extending-tests`. + +.. _TYPO3 slack: https://typo3.slack.com/messages/@danielsiepmann +.. _docker: https://www.docker.com/ +.. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer +.. _reStructuredText: http://docutils.sourceforge.net/rst.html +.. _sphinx: http://www.sphinx-doc.org/en/stable/ diff --git a/Documentation/source/extending.rst b/Documentation/source/extending.rst new file mode 100644 index 0000000..ad71a8a --- /dev/null +++ b/Documentation/source/extending.rst @@ -0,0 +1,94 @@ +.. _extending: + +Extending +========= + +It's possible to extend the provided migrations. + +Also adding tests is pretty easy and done by adding a folder with an input file and an file +holding the expectations. + +.. _extending-sniffs: + +Sniffs +------ + +Follow the official docs of `phpcs`_: +https://github.com/squizlabs/PHP_CodeSniffer/wiki/Coding-Standard-Tutorial#creating-the-sniff + +The following resources might be helpful during working with ``phpcs``: + +- https://secure.php.net/manual/en/tokens.php + +- :file:`CodeSniffer/Tokens.php` + +- :file:`CodeSniffer/File.php` + +.. _extending-tests: + +Tests +----- + +We are using `phpunit` as testing framework. + +Adding tests for sniffs is as easy as providing the same folder structure as for the sniff, just +inside the :file:`tests/Fixtures` folder. Instead of adding the sniff as a file, you have to provide +a folder named like the sniff. E.g. you want to add a test for sniff +:file:`src/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff.php`, the following folder +has to exist: :file:`tests/Fixtures/Standards/Typo3Update/Sniffs/LegacyClassnames/DocCommentSniff/`. + +.. _extending-tests-single: + +Single test per sniff +--------------------- + +Inside of the folder at least a file :file:`InputFileForIssues.php` has to exist, containing PHP +code to use for the test. Also a file :file:`Expected.json` has to exist, with the json result of +calling ``phpcs`` with :file:`InputFileForIssues.php`. + +Everything else is done out of the box. + +If your sniff also implements fixable errors or warnings, you can further provide a +:file:`Expected.diff` which is generated by ``phpcbf``. + +.. _extending-tests-multiple: + +Multiple tests per sniff +------------------------ + +Also it's possible to provide multiple tests for a single sniff, e.g. with different cli arguments +like options for the sniff. In that case you have to place a :file:`Arguments.php` in the folder. +This file returns an array: + +.. code-block:: php + [], + 'customVendor' => [ + 'runtime-set' => [ + 'vendor' => 'MyCustomVendor', + ], + ], + ]; + +In the example above ``defaultVendor`` and ``customVendor` are subfolders containing the same +structure as documented for :ref:`extending-tests-single`. +This way it's possible to run multiple tests per sniff. + +Also you can provide further cli arguments on a key -> value base. Where ``runtime-set`` is special, +as it contains a sub array to provide multiple runtime sets. + +How sniff tests are implemented +------------------------------- + +We just find all folders below :file:`tests/Fixtures/Standards/Typo3Update/Sniffs` ending with +``Sniff`` and check the structure. They are provided to the test itself through a dataprovider in +phpunit. + +We then build the phpcs cli call and execute it against the :file:`InputFileForIssues.php` and +compare the result against the :file:`Expected.json`. Same for :file:`Expected.diff`. The existence +of :file:`Expected.diff` itself will trigger the test for ``phpcbf``. + +.. _phpcs: https://github.com/squizlabs/PHP_CodeSniffer +.. _phpunit: https://phpunit.de/ diff --git a/Documentation/source/features.rst b/Documentation/source/features.rst new file mode 100644 index 0000000..a042484 --- /dev/null +++ b/Documentation/source/features.rst @@ -0,0 +1,110 @@ +.. _features: + +Features +======== + +Migration of old legacy classnames to namespace class names +----------------------------------------------------------- + +Currently we can migrate calls to old legacy class names of the TYPO3 core like ``Tx_Extbase...`` to +new ones like ``\TYPO3\Extbase\...``. This is done for: + +Possible configurations for all sniffs: + +- :ref:`configuration-legacyExtensions` + +Implemented sniffs: + +- PHPDocuments, like Includes and annotations for IDEs. + + Possible extra configurations: + + - :ref:`configuration-allowedTags` + + +- Inheritance like ``extends`` and ``implements``. + +- Static calls like ``t3lib_div::`` to ``\TYPO3\Core\Utility\GeneralUtility``. + +- Static call also checks for ``::class``, as technically we just look before the ``::``. + +- Typehints in methods and function like injects. + +- ``instanceof`` checks. + +- Inline comments for IDEs, e.g. ``/* @var $configurationManager + Tx_Extbase_Configuration_ConfigurationManager */`` + +- Instantiation through ``new``. + +- Instantiation through ``makeInstance``. Only Classnames in Strings are supported, no ``::class``. + +- Instantiation through ``ObjectManager``, check afterwards as this is static and all function calls + using ``get`` and ``create`` will be adjusted. Might be useful to exclude this sniff and run it + separately. + Only Classnames in Strings are supported, no ``::class``. + +- ``use`` statements. + +- ``catch`` of legacy class names. + + +Also definitions of classes, traits and interfaces are migrated too: + +Possible extra configurations: + +- :ref:`configuration-vendor` + + +Definitions are migrated, where namespace is added right after opening php-tag and class name is +replaced with last part. We split by ``_`` as Extbase convention. + +After definitions were migrated, we also migrate the usage in the same way as documented above for +TYPO3 core classes. On first run the definition will be converted, on second run the usage. This is +due to the fact, that PHPCS might find the definition after the usage, so please run twice. + +.. note:: + The configured file will be updated after each run, for each converted class, trait and + interface definition. See :ref:`configuration-mappingFile`. + + +This also covers adding the vendor to plugin and modules in :file:`ext_tables.php` and +:file:`ext_localconf.php`: + +Possible extra configurations: + +- :ref:`configuration-vendor` + + +Add missing vendor to plugin and module registrations and configurations. You might want to set +this to non fixable and warning if you already provide the vendor inside a single Variable, together +with your extension key, as this is not recognized. So the following will be recognized: + + - ``$_EXTKEY,`` + + - ``$VENDOR . $_EXTKEY,`` + + - ``'VENDOR.' . $_EXTKEY,`` + + +While the following will not: + + - ``$key = 'Vendor.' . $_EXTKEY;`` + +Check for removed calls +----------------------- + +Also we check for the following deprecated calls: + +Check for usage of *removed functions* in general. The functions are configured via yaml files. The +location of them is configurable, default is inside the standard itself, and we try to deliver all +information. For configuration options see ``removedFunctionConfigFiles``. + +Check for usage of *removed constants*. The constants are configured in same way as removed +functions. For configuration options see ``removedConstantConfigFiles``. + + +Further checks +-------------- + +- Legacy ajax registrations for TYPO3 Backend. diff --git a/Documentation/source/index.rst b/Documentation/source/index.rst index eeb03d1..93ec3be 100644 --- a/Documentation/source/index.rst +++ b/Documentation/source/index.rst @@ -1,22 +1,69 @@ -.. Automated TYPO3 Update documentation master file, created by - sphinx-quickstart on Thu Apr 13 07:58:42 2017. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +.. _highlight: bash -Welcome to Automated TYPO3 Update's documentation! -================================================== +About +===== -Contents: +Our goal is to provide automated migrations for TYPO3 updates, as much as possible. + +This should include source code modifications like adjusting old legacy class names to new ones and +providing a list of deprecated calls. + +The official project home page can be found at https://git.higidi.com/Automated-TYPO3-Update/automated-typo3-update . +Please open new issues and merge requests there. You can login with your Github account. + +Github is just used as a mirror for the project. + +Requirements +============ + +To install the project you need ``composer`` to be installed and inside your ``$PATH``. +Otherwise run ``make install-composer`` to install composer. + +Installation +============ + +Run:: + + make install + +Afterwards the :ref:`configuration-mappingFile` is required. + +What does it look like? +======================= + +.. code:: + + $ ./vendor/bin/phpcs -p --colors -s + E + + + FILE: + ---------------------------------------------------------------------- + FOUND 5 ERRORS AFFECTING 5 LINES + ---------------------------------------------------------------------- + 8 | ERROR | [x] Legacy classes are not allowed; found + | | backend_toolbarItem + | | (Typo3Update.LegacyClassnames.Inheritance.legacyClassname) + 14 | ERROR | [x] Legacy classes are not allowed; found TYPO3backend + | | (Typo3Update.LegacyClassnames.DocComment.legacyClassname) + 16 | ERROR | [x] Legacy classes are not allowed; found TYPO3backend + | | (Typo3Update.LegacyClassnames.TypeHint.legacyClassname) + 48 | ERROR | [x] Legacy classes are not allowed; found t3lib_extMgm + | | (Typo3Update.LegacyClassnames.StaticCall.legacyClassname) + 61 | ERROR | [x] Legacy classes are not allowed; found t3lib_div + | | (Typo3Update.LegacyClassnames.StaticCall.legacyClassname) + ---------------------------------------------------------------------- + PHPCBF CAN FIX THE 5 MARKED SNIFF VIOLATIONS AUTOMATICALLY + ---------------------------------------------------------------------- + + Time: 35ms; Memory: 5Mb .. toctree:: :maxdepth: 2 + :hidden: - - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` - + features + configuration + usage + extending + contribution diff --git a/Documentation/source/usage.rst b/Documentation/source/usage.rst new file mode 100644 index 0000000..0159d9c --- /dev/null +++ b/Documentation/source/usage.rst @@ -0,0 +1,45 @@ +.. _highlight: bash + +Usage +===== + +If everything is configured, you can run:: + + ./vendor/bin/phpcbf + +This will run the auto fixer recursive for ```` fixing all issues. + +For some tasks you need to run the above command twice, e.g. for namespace migrations. + +Afterwards you should run:: + + ./vendor/bin/phpcs + +To get information about possible issues that were not autofixed. + +To prevent issues, use the following setup:: + + ./vendor/bin/phpcs --standard=Typo3Update -p --colors --runtime-set mappingFile + +Same for ``phpcbf``. + +Further examples +---------------- + +You might want to add ``-p --colors`` to see that something is happening. + +Also make sure to ignore certain files like libraries or js and css files while running the update. +Check out the official docs for how to do so. + +FAQ +--- + +I do not see any issues regarding TYPO3 update but lots of coding style. + Then you probably have a :file:`phpcs.xml` in your project taking precedence. Add the + ``-standard=`` argument to the call:: + + ./vendor/bin/phpcs --standard=Typo3Update + +I see the error message ``Failed opening required 'Standards/Typo3Update/Sniffs/../../../../LegacyClassnames.php'`` + Then you didn't configure :ref:`configuration-mappingFile`, check the link and update the + configuration.