diff --git a/README.rst b/README.rst index 21f2be0..7075c36 100644 --- a/README.rst +++ b/README.rst @@ -1,216 +1,6 @@ -TYPO3 Exception Page Creation -============================= +Archived: TYPO3 Exception Page Creation +======================================= -Besides editing existing -`TYPO3 Exception Pages `_ -on docs.typo3.org, the user should also be able to create a new exception page – -without being distracted from the usual workflow. - -Therefore, the web server simulates a default exception page with the familiar -"Edit on GitHub" button when it cannot find the requested exception page. -When the user clicks the button to add their experience with this exception, -the web server creates the new exception page on-the-fly before redirecting -the user to the usual GitHub edit form. - -This is the same exception page creation screen of the former wiki.typo3.org -and the future docs.typo3.org instance: - -.. table:: - :widths: auto - - ================================================ ================================================ - Wiki (old) Docs (new) - ================================================ ================================================ - .. image:: docs/exception_page_creation_wiki.png .. image:: docs/exception_page_creation_docs.png - ================================================ ================================================ - -Installation ------------- - -1. Install `Docker `_ and `Docker-Compose `_. -2. Build the environment by - - .. code-block:: bash - - # Linux - make build - - # MacOS and Windows - docker-compose build --force-rm - docker-compose -f admin.yml run --rm composer-install - -3. Copy ``app/config.inc.php`` to ``app/config.php`` and insert - the GitHub username and token of the user who has write access to the - `TYPO3 Exception Pages repository `_ - via GitHub API. See the - `GitHub Docs `_ - for further details on how to create an access token. - -Maintenance ------------ - -.. _fetch-exception-codes: - -Fetch Exception Codes -~~~~~~~~~~~~~~~~~~~~~ - -1. Get the list of available exception codes for each TYPO3 release by running - - .. code-block:: bash - - # Linux - make fetch - - # MacOS and Windows - docker-compose -f admin.yml run --rm fetch-exception-code-files - - It pulls the current TYPO3 Git repository, checks out each TYPO3 release and - creates an according exception code file in folder - ``app/packages/exception-pages/res/exceptions`` - if it does not exist - already. - -2. Merge all exception code files into one final aggregation file by - - .. code-block:: bash - - # Linux - make merge - - # MacOS and Windows - docker-compose -f admin.yml run --rm merge-exception-code-files - - It traverses all JSON files and produces the final PHP file - ``app/packages/exception-pages/res/exceptions/exceptions.php`` which serves - as the list of exception codes available for page creation. - -– or, instead of (1) and (2) – - -3. Combine both commands of fetching and merging new exception codes by - - .. code-block:: bash - - # Linux - make update - - # MacOS and Windows - docker-compose -f admin.yml run --rm update-exception-code-files - -Repeat these steps always when a new TYPO3 version has been released. - -.. _refresh-exception-page-templates: - -Refresh Exception Page templates -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The default exception page template is fetched from an existing exception page -and exception code specific parts are replaced with placeholders. The lifetime -of the template is 8 days, so changes in the general docs.typo3.org template -are reflected in the default exception page in a timely manner. -Update the templates manually by - -.. code-block:: bash - - # Linux - make refresh - - # MacOS and Windows - docker-compose -f admin.yml run --rm refresh-templates - -.. _manual-testing: - -Manual testing --------------- - -1. Bring up the webserver by - - .. code-block:: bash - - # Linux - make start - - # MacOS and Windows - docker-compose up - -2. Chose an arbitrary exception number from the array of exception code file - ``app/packages/exception-pages/res/exceptions/exceptions.php``. - Make sure, that the corresponding TYPO3 Exception Page does not exist yet at - - .. code-block:: - - https://github.com/TYPO3-Documentation/TYPO3CMS-Exceptions/Documentation/Exceptions/{exceptionnumber}.rst - -3. Open your browser at - - .. code-block:: - - http://localhost:8080/exceptions/{exceptionnumber}.html - - and confirm that it looks like an ordinary TYPO3 Exception Page. - -4. Click the "Edit on GitHub" button and confirm that you get redirected to - the usual GitHub edit form for file - - .. code-block:: - - https://github.com/TYPO3-Documentation/TYPO3CMS-Exceptions/Documentation/Exceptions/{exceptionnumber}.rst - -5. Cancel the editing and confirm that there is a new commit in the repository - history with commit message - - .. code-block:: - - [TASK] Create page for exception {exceptionnumber} - -6. Confirm that repeating clicks on the "Edit on GitHub" button do not end in - errors. -7. Bring down the webserver by - - .. code-block:: bash - - # Linux - make stop - - # MacOS and Windows - docker-compose down - -Automatic testing ------------------ - -Run the integrated tests by - -.. code-block:: bash - - # Linux - make tests - - # MacOS and Windows - docker-compose -f admin.yml run --rm run-tests - -Deployment ----------- - -1. The essence for the production environment is - - * the PHP application in folder `app `_ - * the Nginx configuration in file `default.conf `_ - -2. Each push to the remote branch ``main`` triggers a deployment to the production - server. Thus make sure that you - - * fetched, merged and committed the latest exception codes as written in - `Fetch Exception Codes `_ - * fetched, merged and committed the latest page templates as written - in `Refresh Exception Page template `_ - -Uninstallation --------------- - -Remove the environment from your operating system by - -.. code-block:: bash - - # Linux - make clean - - # MacOS and Windows - docker-compose down --rmi all --volumes +Creation of exception pages is now done directly via +https://github.com/TYPO3-Documentation/TYPO3CMS-Exceptions/tree/main/.github/workflows. +This repository is therefore archived.