Updated documentation

.gitattributes

@@ -3,6 +3,7 @@
 /.github export-ignore
 /dev export-ignore
 /docs export-ignore
+/docs_includes export-ignore
 
 /.all-contributorsrc export-ignore
 /.gitattributes export-ignore

.github/workflows/docs.yml

@@ -0,0 +1,39 @@
+name: MkDocs
+
+on:
+  workflow_call:
+  # Allow manually triggering the workflow.
+  workflow_dispatch:
+
+  push:
+    branches:
+      - main
+      - documentation
+    paths:
+      - 'docs/**.md'
+      - 'docs/**.html'
+      - 'docs/**.yml'
+      - 'docs_includes/**.md'
+      - 'mkdocs.yml'
+permissions:
+  contents: write
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV
+
+      - uses: actions/cache@v3
+        with:
+          key: mkdocs-material-${{ env.cache_id }}
+          path: .cache
+          restore-keys: |
+            mkdocs-material-
+      - run: pip3 install mkdocs mkdocs-material mkdocs-minify-plugin mkdocs-redirects
+
+      - name: Publish docs
+        run: mkdocs gh-deploy --force

.gitignore

@@ -79,6 +79,9 @@ phpstan*.neon
 /shell/update-copyright.php
 /shell/translations.php
 
+# generated by mkdocs serve
+/site
+
 # DDEV
 .ddev/config.yaml
 .ddev/.sampleData

docs/content/developers/changelog/index.md

@@ -0,0 +1,109 @@
+# Important changes
+
+Most important changes will be listed here, all other changes since `19.4.0` can be found in
+[release](https://github.com/OpenMage/magento-lts/releases) notes.
+
+## Between Magento 1.9.4.5 and OpenMage 19.x
+
+- bug fixes and PHP 7.x, 8.0, 8.1 and 8.2 compatibility
+- added config cache for system.xml ([#1916](https://github.com/OpenMage/magento-lts/pull/1916))
+- added `frontend_type` `color` ([#2945](https://github.com/OpenMage/magento-lts/pull/2945))
+- search for `null` ("NULL") in backend grids ([#1203](https://github.com/OpenMage/magento-lts/pull/1203))
+- removed `lib/flex` containing unused ActionScript "file uploader" files ([#2271](https://github.com/OpenMage/magento-lts/pull/2271))
+- `Mage_Catalog_Model_Resource_Abstract::getAttributeRawValue()` now returns `'0'` instead of `false` if the value stored in the database is `0` ([#572](https://github.com/OpenMage/magento-lts/pull/572))
+- PHP extension `intl` is required
+- Deprecation errors are not suppressed anymore
+- removed modules:
+    - `Mage_Backup` ([#2811](https://github.com/OpenMage/magento-lts/pull/2811))
+    - `Mage_Compiler`
+    - `Mage_GoogleBase`
+    - `Mage_PageCache` ([#2258](https://github.com/OpenMage/magento-lts/pull/2258))
+    - `Mage_Poll` ([#3098](https://github.com/OpenMage/magento-lts/pull/3098))
+    - `Mage_Xmlconnect`
+    - `Phoenix_Moneybookers`
+
+_If you rely on those modules you can reinstall them with composer:_
+
+- Module `Mage_Backup`
+
+  ```bash
+  composer require openmage/module-mage-backup
+  ```
+
+- Module `Mage_PageCache`
+
+  ```bash
+  composer require openmage/module-mage-pagecache
+  ```
+
+- Module `Mage_Poll`
+
+  ```bash
+  composer require openmage/module-mage-poll
+  ```
+
+- Legacy frontend themes
+
+  ```bash
+  composer require openmage/legacy-frontend-themes
+  ```
+
+## Between OpenMage 19.x and 20.x
+
+Do not use 20.x.x if you need IE support.
+
+- removed IE conditional comments, IE styles, IE scripts and IE eot files ([#1073](https://github.com/OpenMage/magento-lts/pull/1073))
+- removed frontend default themes (default, modern, iphone, german, french, blank, blue) ([#1600](https://github.com/OpenMage/magento-lts/pull/1600))
+- fixed incorrect datetime in customer block (`$useTimezone` parameter) ([#1525](https://github.com/OpenMage/magento-lts/pull/1525))
+- added redis as a valid option for `global/session_save` ([#1513](https://github.com/OpenMage/magento-lts/pull/1513))
+- reduce needless saves by avoiding setting `_hasDataChanges` flag ([#2066](https://github.com/OpenMage/magento-lts/pull/2066))
+- removed support for `global/sales/old_fields_map` defined in XML ([#921](https://github.com/OpenMage/magento-lts/pull/921))
+- enabled website level config cache ([#2355](https://github.com/OpenMage/magento-lts/pull/2355))
+- made overrides of `Mage_Core_Model_Resource_Db_Abstract::delete` respect parent api ([#1257](https://github.com/OpenMage/magento-lts/pull/1257))
+- rewrote `Mage_Eav_Model_Config` as cache for all eav entity and attribute reads ([#2993](https://github.com/OpenMage/magento-lts/pull/2993))
+
+For full list of changes, you can [compare tags](https://github.com/OpenMage/magento-lts/compare/1.9.4.x...20.0).
+
+## Since OpenMage 19.5.0 / 20.1.0
+
+PHP 7.4 is now the minimum required version.
+
+Most of the 3rd party libraries/modules that were bundled in our repository were removed and migrated to composer dependencies.
+This allows for better maintenance and upgradability.
+
+Specifically:
+
+- `phpseclib`
+- `mcrypt_compat`
+- `Cm_RedisSession`
+- `Cm_Cache_Backend_Redis`
+- `Pelago_Emogrifier` ([#2411](https://github.com/OpenMage/magento-lts/pull/2411))
+- Zend Framework 1 ([#2827](https://github.com/OpenMage/magento-lts/pull/2827))
+
+If your project uses OpenMage through composer then all dependencies will be managed automatically.  
+If you just extracted the release zip/tarball in your project's main folder then be sure to:
+- remove the old copy of aforementioned libraries from your project, you can do that with this command:
+  ```bash
+  rm -rf app/code/core/Zend lib/Cm lib/Credis lib/mcryptcompat lib/Pelago lib/phpseclib lib/Zend
+  ```
+
+- download the new release zip file that is named `openmage-VERSIONNUMBER.zip`, this one is built to contain the `vendor`
+  folder generated by composer, with all the dependencies in it
+- extract the zip file in your project's repository as you always did
+
+We also decided to remove our Zend_DB patches (that were stored in `app/code/core/Zend`) because they were very old and
+not compatible with the new implementations made by ZF1-Future, which is much more advanced and feature rich.
+This may generate a problem with `Zend_Db_Select` statements that do not use `Zend_Db_Expr` to quote expressions.
+If you see SQL errors after upgrading please remember to check for this specific issue in your code.
+
+UPS shut down their old CGI APIs, so we removed the support for it from the `Mage_Usa` module.
+
+## Between OpenMage 20.x and 21.x (unreleased, available on branch `next`)
+
+- PHP 8.1 as minimum required version
+- Removed `scriptaculous/dragdrop.js` ([#3215](https://github.com/OpenMage/magento-lts/pull/3215))
+- RWD theme: updated jQuery to 3.7.0 ([#3204](https://github.com/OpenMage/magento-lts/pull/3204))
+- Unified CSRF configuration ([#3147](https://github.com/OpenMage/magento-lts/pull/3147)) and added form key validation to Contacts form ([#3146](https://github.com/OpenMage/magento-lts/pull/3146))
+- Removed double span element from HTML buttons ([#3123](https://github.com/OpenMage/magento-lts/pull/3123))
+- Removed all deprecated `Mysql4_` classes ([#2730](https://github.com/OpenMage/magento-lts/pull/2730)). If there are any old modules/extensions in your installation that use such classes, you must run `shell/rename-mysql4-class-to-resource.php` in the command line in order to convert them. Backup all files before running the script
+- Removed "admin routing compatibility mode" ([#1551](https://github.com/OpenMage/magento-lts/pull/1551))

docs/content/developers/changelog/new-config.md

@@ -0,0 +1,17 @@
+---
+tags:
+- Configuration
+---
+
+# New Config Options
+
+- `admin/design/use_legacy_theme`
+- `admin/global_search/enable`
+- `admin/emails/admin_notification_email_template`
+- `catalog/product_image/progressive_threshold`
+- `catalog/search/search_separator`
+- `dev/log/max_level`
+- `newsletter/security/enable_form_key`
+- `sitemap/category/lastmod`
+- `sitemap/page/lastmod`
+- `sitemap/product/lastmod`

docs/content/developers/changelog/new-events.md

@@ -0,0 +1,16 @@
+---
+tags:
+- Events
+---
+
+# New Events
+
+- `adminhtml_block_widget_form_init_form_values_after`
+- `adminhtml_block_widget_tabs_html_before`
+- `adminhtml_sales_order_create_save_before`
+- `checkout_cart_product_add_before`
+- `core_app_run_after`
+- `sitemap_cms_pages_generating_before`
+- `sitemap_urlset_generating_before`
+
+[Full list of events](../events/list.md)

docs/content/developers/changelog/soap-wsdl.md

@@ -0,0 +1,24 @@
+# SOAP/WSDL
+
+Since `19.4.17`/`20.0.15` we changed the `targetNamespace` of all the WSDL files (used in the API modules), from `Magento` to `OpenMage`.
+If your custom modules extends OpenMage's APIs with a custom WSDL file and there are some hardcoded `targetNamespace="urn:Magento"` strings, your APIs may stop working.
+
+Please replace all occurrences of
+
+```
+targetNamespace="urn:Magento"
+```
+with
+```
+targetNamespace="urn:OpenMage"
+```
+or alternatively
+```
+targetNamespace="urn:{{var wsdl.name}}"
+```
+to avoid any problem.
+
+To find which files need the modification you can run this command from the root directory of your project.
+```bash
+grep -rn 'urn:Magento' --include \*.xml
+```

docs/DDEV.md → docs/content/developers/ddev.md

@@ -1,26 +1,40 @@
-# OpenMage Environment Based on DDEV (https://ddev.com/)
+# DDEV based environment
+
+See: https://ddev.com
 
 ## Using n98-magerun
 
-You can use the swiss army knife for Magento developers, sysadmins and devops. The tool provides a huge set of well tested command line commands which save hours of work time. 
+You can use the swiss army knife for Magento developers, sysadmins and devops. The tool provides a huge set of well tested command line commands which save hours of work time.
 
-Run any n98-magerun command in the terminal window by adding **ddev** in front of it. For example `ddev magerun sys:info` prints infos about the current OpenMage system. 
+Run any n98-magerun command in the terminal window by adding **ddev** in front of it. For example `ddev magerun sys:info` prints infos about the current OpenMage system.
 
 For more information about the available commands please visit https://n98-magerun.readthedocs.io/en/latest/index.html.
 
 ## Using phpMyAdmin
 
-Run in the terminal window `ddev get ddev/ddev-phpmyadmin` to install the phpMyAdmin add-on then restart DDEV. 
+Run in the terminal window to install the phpMyAdmin add-on then restart DDEV.
+
+```bash
+ddev get ddev/ddev-phpmyadmin
+```
+
+To launch phpMyAdmin in the browser run in the terminal window.
 
-To launch phpMyAdmin in the browser run in the terminal window `ddev phpmyadmin`.
+```bash
+ddev phpmyadmin
+```
 
 ## Using Mailpit
 
-To launch Mailpit in the browser run in the terminal window `ddev mailpit`.
+To launch Mailpit in the browser run in the terminal window.
+
+```bash
+ddev mailpit
+```
 
 ## Setting up cronjobs
 
-Run in the terminal window `ddev get ddev/ddev-cron` to install the cron add-on then restart DDEV. 
+Run in the terminal window `ddev get ddev/ddev-cron` to install the cron add-on then restart DDEV.
 
 By default the OpenMage cronjob runs every minute. If you want to change it edit the file `.ddev/web-build/openmage.cron`.
 
@@ -47,7 +61,7 @@ web_environment: [
 
 Every DDEV project is automatically configured with Xdebug so that popular IDEs can do step debugging of PHP code. Xdebug is a server-side tool and it is installed automatically in the container so you do not have to install or configure it on your workstation. Xdebug is disabled by default for performance reasons, so you will need to enable it and configure your IDE before can start debugging. For more information, please visit https://ddev.readthedocs.io/en/latest/users/debugging-profiling/step-debugging/.
 
-Run the following commands in the terminal window to enable or disable xDebug 
+Run the following commands in the terminal window to enable or disable xDebug
 
 `ddev xdebug on`
 
@@ -69,7 +83,9 @@ Please note that DDEV changes the port numbers on every restart. If you want to
 host_db_port: 6000
 ```
 
-## Using Browsersync (https://github.com/ddev/ddev-browsersync)
+## Using Browsersync
+
+See: https://github.com/ddev/ddev-browsersync
 
 Browsersync features live reloads, click mirroring, network throttling. Run the following commands in the terminal window
 
@@ -79,7 +95,9 @@ ddev restart
 ddev browsersync
 ```
 
-## Installing Compass (http://compass-style.org/)
+## Installing Compass
+
+See: https://compass-style.org
 
 Compass is required for editing SCSS files.
 
@@ -126,7 +144,9 @@ You can use flags, for example `ddev openmage-install -d -s -k -q`
 
 **2. By default, running the `ddev config` command does not create an administrator account. If you want to create or update one run in the terminal window `ddev openmage-admin` and follow the steps.**
 
-## Useful DDEV commands (https://ddev.readthedocs.io/en/latest/users/usage/commands)
+## Useful DDEV commands
+
+See: https://ddev.readthedocs.io/en/latest/users/usage/commands
 
 Run in the terminal window any of the following commands for different tasks.
 
@@ -194,9 +214,11 @@ Run in the terminal window any of the following commands for different tasks.
 
 `ddev clean --dry-run -all`, `ddev clean`
 
-## Using mkcert for secured connections (https://github.com/FiloSottile/mkcert)
+## Using mkcert for secured connections
+
+See: https://github.com/FiloSottile/mkcert
 
-mkcert is a simple tool for making locally-trusted development certificates. If you use (Windows 10/11 + WSL + Docker), first install the mkcert package in Windows then copy the certificates files associated to the current user into the Linux distribution. 
+mkcert is a simple tool for making locally-trusted development certificates. If you use (Windows 10/11 + WSL + Docker), first install the mkcert package in Windows then copy the certificates files associated to the current user into the Linux distribution.
 
 For example, copy `rootCA.pem` and `rootCA-key.pem`
 

docs/ERROR_PAGE.md → docs/content/developers/error-pages.md

@@ -1,6 +1,8 @@
-## For Multistore setups
+# Error pages
 
-If you want to setup multiple stores with a different layout and localized content for each store, this is done by passing the `$_GET['skin']` parameter to the intended processor In the example below, we are using a `503` type error template file, which requires localized content.
+## Introduction
+
+If you want to set up multiple stores with a different layout and localized content for each store, this is done by passing the `$_GET['skin']` parameter to the intended processor In the example below, we are using a `503` type error template file, which requires localized content.
 
 The constructor of the `Error_Processor` class accepts a `skin` GET parameter to change layout:
 
@@ -12,23 +14,35 @@ if (isset($_GET['skin'])) {
 
 This can also be added a rewrite rule in the `.htaccess` file that will append a `skin` parameter to the URL.
 
-### $_GET['skin'] parameter
+## The `$_GET['skin']` parameter
 
 To use the `skin` parameter:
 
 1. Check if the `maintenance.flag` exists
-1. Note the host address, that refers to the `HTTP_HOST`, or any other variable such as ENV variables
-1. Check if the `skin` parameter exists
-1. Set the parameter by using the rewrite rules below.
+2. Note the host address, that refers to the `HTTP_HOST`, or any other variable such as ENV variables
+3. Check if the `skin` parameter exists
+4. Set the parameter by using the rewrite rules below.
+
+## Rewrite rule
 
 This is what it looks like as a rewrite rule:
 
-```
-RewriteCond `%{DOCUMENT_ROOT}/maintenance.flag -f
-RewriteCond `%{HTTP_HOST} ^sub.example.com$`
-RewriteCond `%{QUERY_STRING} !(^|&)skin=sub(&|$)` [NC]
-RewriteRule `^ %{REQUEST_URI}?skin=sub` [L]
-```
+=== "Apache"
+
+    ```
+    RewriteCond `%{DOCUMENT_ROOT}/maintenance.flag -f
+    RewriteCond `%{HTTP_HOST} ^sub.example.com$`
+    RewriteCond `%{QUERY_STRING} !(^|&)skin=sub(&|$)` [NC]
+    RewriteRule `^ %{REQUEST_URI}?skin=sub` [L]
+    ```
+
+=== "Nginx"
+
+    !!! question
+
+        The setting should be added for multistore setups.
+
+## Copy files
 
 Copy the following files:
 
@@ -38,6 +52,3 @@ Copy the following files:
 Edit these files to provide localized content in the `503.phtml` file and custom styling in the `styles.css` file.
 
 Ensure your paths point to your `errors` directory. The directory name must match the URL parameter indicated in the RewriteRule. In the example above, the `sub` directory is used, which is specified as a parameter in the RewriteRule (`skin=sub`)
-
-### ToDo: nginx
-The nginx setting should be added for multistore setups.