docs(upgrading): Complete MODX 2.x minor upgrade notes

en/getting-started/maintenance/upgrading.md

@@ -66,12 +66,16 @@ It's a good idea to clear your browser cache after upgrading. Browsers often cac
 
 For changes relating to specific versions, please see the following pages:
 
-- [For Upgrading to 2.2](getting-started/maintenance/upgrading/2.2 "Upgrading to 2.2.x")
-- [For Upgrading From 2.0.x to 2.1.x](getting-started/maintenance/upgrading/2.1 "Upgrading from 2.0.x to 2.1.x") **!important**
-- [For Upgrades Coming From Prior to 2.0.5](getting-started/maintenance/upgrading/2.0.5 "Upgrading from Versions Earlier than 2.0.5")
-- [For Upgrades Coming From Prior to 2.0.0-rc2](getting-started/maintenance/upgrading/2.0.0-rc2 "Upgrading to Revolution 2.0.0-rc-2")
-
-Upgrades after 2.0.0-rc-2 should run smoothly without issues.
+- [Upgrading to 2.8](getting-started/maintenance/upgrading/2.8), then the security-related changes in [2.8.2 / 2.8.3](getting-started/maintenance/upgrading/2.8.2)
+- [Upgrading to 2.7](getting-started/maintenance/upgrading/2.7)
+- [Upgrading to 2.6](getting-started/maintenance/upgrading/2.6)
+- [Upgrading to 2.5](getting-started/maintenance/upgrading/2.5)
+- [Upgrading to 2.4](getting-started/maintenance/upgrading/2.4)
+- [Upgrading to 2.3](getting-started/maintenance/upgrading/2.3)
+- [Upgrading to 2.2](getting-started/maintenance/upgrading/2.2)
+- [Upgrading from 2.0.x to 2.1.x](getting-started/maintenance/upgrading/2.1) **!important**
+- [Upgrades from prior to 2.0.5](getting-started/maintenance/upgrading/2.0.5)
+- [Upgrades from prior to 2.0.0-rc2](getting-started/maintenance/upgrading/2.0.0-rc2)
 
 ## See Also
 
@@ -96,9 +100,14 @@ See the note above about FTP clients that support directory merging.
 ### Related Articles
 
 1. [Troubleshooting Upgrades](getting-started/maintenance/upgrading/troubleshooting)
-2. [Upgrading to 2.2.x](getting-started/maintenance/upgrading/2.2)
-3. [Upgrading from 2.0.x to 2.1.x](getting-started/maintenance/upgrading/2.1)
-4. [Upgrading from Versions Earlier than 2.0.5](getting-started/maintenance/upgrading/2.0.5)
-5. [Upgrading to Revolution 2.0.0-rc-2](getting-started/maintenance/upgrading/2.0.0-rc2)
-6. [Upgrading from MODX Evolution](getting-started/maintenance/upgrading/evolution)
-7. [Functional Changes from Evolution](getting-started/maintenance/upgrading/evolution/functional-changes)
+2. [Upgrading to 2.8](getting-started/maintenance/upgrading/2.8)
+3. [Upgrading to 2.8.2 / 2.8.3](getting-started/maintenance/upgrading/2.8.2)
+4. [Upgrading to 2.7](getting-started/maintenance/upgrading/2.7)
+5. [Upgrading to 2.6](getting-started/maintenance/upgrading/2.6)
+6. [Upgrading to 2.5](getting-started/maintenance/upgrading/2.5)
+7. [Upgrading to 2.4](getting-started/maintenance/upgrading/2.4)
+8. [Upgrading to 2.3](getting-started/maintenance/upgrading/2.3)
+9. [Upgrading to 2.2.x](getting-started/maintenance/upgrading/2.2)
+10. [Upgrading from 2.0.x to 2.1.x](getting-started/maintenance/upgrading/2.1)
+11. [Upgrading from MODX Evolution](getting-started/maintenance/upgrading/evolution)
+12. [Functional Changes from Evolution](getting-started/maintenance/upgrading/evolution/functional-changes)

en/getting-started/maintenance/upgrading/2.4.md

@@ -0,0 +1,55 @@
+---
+title: "Upgrading to 2.4"
+sortorder: 95
+---
+
+MODX Revolution 2.4.0 (August 2015) adds package dependencies, namespace permissions, database indexes, and manager improvements. Full changelog: [`core/docs/changelog.txt`](https://github.com/modxcms/revolution/blob/2.x/core/docs/changelog.txt).
+
+Release overviews:
+
+- [Revolution 2.4 — Package Dependencies & More](https://modx.com/blog/2015/08/19/revolution-2.4/)
+- [Deep Dive Into MODX Revolution 2.4](https://modx.com/blog/2015/08/26/deep-dive-into-modx-revolution-2.4/)
+
+## Before you upgrade
+
+- Upgrade to the latest 2.4 patch release, rather than stopping at 2.4.0. The 2.4 line includes the security fix from 2.3.6.
+- Update Extras on the current version, clear `core/cache`, flush sessions, and back up the database and files.
+- Check custom integrations with `modTransportProvider`. MODX 2.4.1 restored compatibility for Extras that used its previous behaviour.
+
+## Changes to review
+
+### User profile country values
+
+`modUserProfile.country` stores ISO country codes instead of translated country names. Check imports, exports, profile forms, and reports that compare this field with a full country name.
+
+### Resource URI generation
+
+The `use_frozen_parent_uris` setting lets child URI generation respect frozen parent URIs. Review generated aliases if your site freezes resource URIs or builds paths in custom code.
+
+### Access control and namespaces
+
+2.4 adds namespace permissions and combines the user-group tree with a user grid in the ACL page. Re-test custom access policies and manager users after setup.
+
+### Package dependencies
+
+Transport packages can declare dependencies on other Extras. Package Manager resolves those dependencies and may show setup options during installation. Test packages with custom resolvers or setup-option windows.
+
+## Other notable additions
+
+- New database indexes for common queries.
+- System Events management page.
+- Real-time resource alias generation.
+- Regular-expression validation for text TVs.
+- Date TVs can hide the time input.
+- Custom icons for media sources and contexts.
+- New `saveObject` and `removeObject` methods in object processors.
+- JSONP support in `modConnectorResponse`.
+- `contentType=string` support in `modRestCurlClient`.
+
+## Patch-level caution
+
+2.4.3 introduced a regression in output filters on undefined placeholders. MODX 2.4.4 fixed it. Install the latest 2.4.x patch and test pages that apply output modifiers to missing values.
+
+## After setup
+
+Check manager login, ACLs, Package Manager dependency resolution, user profile country values, and friendly URLs. Clear the manager browser cache before testing.

en/getting-started/maintenance/upgrading/2.5.md

@@ -0,0 +1,44 @@
+---
+title: "Upgrading to 2.5"
+sortorder: 93
+---
+
+MODX Revolution 2.5.0 (April 2016) focused on PHP 7 readiness, manager usability, and anonymous-request performance. Full changelog: [`core/docs/changelog.txt`](https://github.com/modxcms/revolution/blob/2.x/core/docs/changelog.txt).
+
+Release overview: [MODX Revolution 2.5—PHP 7, Performance and More](https://modx.com/blog/2016/04/21/modx-revolution-2.5/).
+
+## Before you upgrade
+
+- Confirm the host can run PHP 5.3+ for 2.5.x. Prefer PHP 7 if the host offers it. PHP 7 support landed in this line (`modPhpThumb` and related fixes).
+- Update Extras on the current version first, then clear `core/cache` and flush sessions before setup.
+
+## Behaviour changes
+
+### `anonymous_sessions`
+
+2.5 adds the [`anonymous_sessions`](building-sites/settings/anonymous_sessions) setting so anonymous front-end hits can skip PHP sessions.
+
+- Default is Yes (sessions for anonymous users still exist unless you change it).
+- Set it to No only as a **context** setting on a front-end context that does not need sessions. Putting No in System Settings can lock you out of the manager.
+
+### Manager JS/CSS compression
+
+`compress_js` no longer builds minified manager assets on the fly. The core ships prebuilt `min.js` / CSS bundles instead. That removes a common source of broken managers after minifier failures. Site developers who patch core manager assets must rebuild those bundles; normal upgrades do not need extra steps.
+
+### Upgrade cleanup
+
+Setup removes selected legacy core files during upgrade. Keep a backup of the tree before you run setup so you can compare if a custom patch lived in a removed path.
+
+## Other additions
+
+- More mobile-friendly manager layout and login accessibility work.
+- New default manager template / starter content for fresh installs.
+- Output filters `stripmodxtags` and `htmlspecial`.
+- Zip unpack in the media/file tree.
+- `modParsedManagerController` for CMPs that use snippets and chunks.
+- Uberbar can search by resource ID.
+- Smarty and PHPMailer library updates (Smarty BC restored in 2.5.0-rc2).
+
+## After setup
+
+Clear the browser cache for the manager domain so you load the new static asset bundles. Re-test login, Package Manager, and any Extra that hooks manager JS.

en/getting-started/maintenance/upgrading/2.6.md

@@ -0,0 +1,46 @@
+---
+title: "Upgrading to 2.6"
+sortorder: 92
+---
+
+MODX Revolution 2.6.0 (November 2017) is a large stability and manager UX release. Full changelog: [`core/docs/changelog.txt`](https://github.com/modxcms/revolution/blob/2.x/core/docs/changelog.txt).
+
+Release overview: [A Major New Milestone for MODX Revolution](https://modx.com/blog/modx-revolution-2-6).
+
+## Before you upgrade
+
+- Prefer 2.5.8 (or later 2.5.x) as the starting point when you can. Older 2.x sites still upgrade, but Extras and custom code need more careful testing.
+- Update packages, clear `core/cache`, flush sessions, then run setup.
+
+## Database notes
+
+### InnoDB on new installs
+
+New MySQL installs create tables with the **InnoDB** engine when the server supports it. Existing MyISAM sites keep their current engines after upgrade. You can convert later if you want InnoDB benefits. See [How to change your MyISAM DB to InnoDB using phpMyAdmin](https://modx.com/blog/convert-myisam-to-innodb-with-phpmyadmin).
+
+### utf8mb4 indexes
+
+Index prefixes on `varchar` / `text` columns were shortened so MySQL can use **utf8mb4**. That mainly matters for new installs and for hosts that already use utf8mb4. If you change collation manually after upgrade, check index lengths against MySQL limits.
+
+## Behaviour and security
+
+- **TV `@EVAL` binding:** set [`allow_tv_eval`](building-sites/settings/allow_tv_eval) to No to disable EVAL bindings (`#13224`). Turn it off on production if you do not need it.
+- **Cached vs uncached tags:** processing of non-cacheable elements inside cacheable ones was fixed (`#13530`). Re-check pages that mix `!` tags inside cached chunks/snippets.
+- **`failed_login_attempts`:** the setting is honoured again (`#13516`). Confirm lockout behaviour matches what you expect.
+- **PHP 7:** session callback and related PHP 7 errors in this line were addressed. On PHP 7 hosts, still confirm manager login and that a front-end session works.
+- Package install / uninstall / remove fire new events (`#12936`). Custom plugins that assume the old event set should be reviewed.
+
+## Manager and API additions
+
+- Who's Online dashboard widget.
+- SVG previews in the Media Browser.
+- Custom manager top menus (`#12554`).
+- `OnResourceCacheUpdate` event for third-party cache layers.
+- Option to skip resource duplication when duplicating a context.
+- `.less`, `.scss`, `.sass`, and `.css.map` among default allowed upload types.
+- DKIM-related PHPMailer attributes.
+- REST: `OPTIONS` on `modRestController`, stream upload support for binary files.
+
+## After setup
+
+Clear the manager browser cache. Check Package Manager, media uploads, login lockout, and any dashboard widgets. On MyISAM hosts, convert to InnoDB only after a full database backup.

en/getting-started/maintenance/upgrading/2.7.md

@@ -0,0 +1,55 @@
+---
+title: "Upgrading to 2.7"
+sortorder: 91
+---
+
+MODX Revolution 2.7.0 (November 2018) adds Trash Manager, native password hashing, static-element automation, and Media Browser security fixes. Full changelog: [`core/docs/changelog.txt`](https://github.com/modxcms/revolution/blob/2.x/core/docs/changelog.txt).
+
+Release overview: [Revolution 2.7: An Impressive and Feature-Packed Release](https://modx.com/blog/modx-revolution-2.7).
+
+## Before you upgrade
+
+- Merge **all** core files from the release package. Incomplete uploads (especially under `core/docs/` and setup templates) have produced broken `config.inc.php` writes when obsolete keys like `cache_disabled` disappeared from the templates.
+- Keep a copy of `core/config/config.inc.php` before setup. If setup writes unresolved `{placeholders}` into that file, restore the backup and run setup again with a complete file tree.
+- Update Extras, clear `core/cache`, flush sessions.
+
+## Breaking changes
+
+### Removed settings
+
+2.7 removes the non-functional `cache_disabled` system setting and drops `cache_system_settings` from system settings. Do not reintroduce those keys by hand. If an old deploy script or Extra still writes them, clean that up after upgrade.
+
+### Password hashing
+
+User passwords use **native PHP password hashing** (`#13926`). Existing hashes keep working through the normal login upgrade path. Custom user-import or password-reset scripts that assume plain MD5 need to follow the current hash class / `hash_class` behaviour instead of writing raw MD5 into `modUser`.
+
+### Deprecated 0.9.x parser utilities
+
+Migration helpers aimed at the old 0.9.x parser are deprecated and logged for removal in 3.0 (`#14131`). Finish any leftover migration work before you jump to MODX 3.
+
+### Media Browser and paths
+
+- Invalid relative media source paths no longer expose filesystem roots (`#14038`).
+- Clearing `modFileRegister` no longer deletes arbitrary paths (`#13980`).
+- phpThumb receives filtered user parameters (`#13979`).
+
+Re-test custom media sources that rely on unusual relative bases.
+
+## Features to configure after upgrade
+
+- **Trash Manager** for restore / purge of deleted resources (`#14058`).
+- **Automatic static elements** workflow (`#14135`) if you keep elements on disk.
+- **`automatic_template_assignment`** (`#13700`).
+- Resource option **Use current alias in alias path** to omit a resource segment from the URI (`#11153`).
+- **`set_sudo`** permission (`#13807`) for controlled sudo elevation.
+- **Purge Old Versions** in Package Management (`#12818`).
+- Composer-oriented project install plus **CLI setup** script (`#13790`).
+- Customisable error.log location (`#13768`) and configurable custom error handler class path (`#14119`).
+- Output filter `filterPathSegment` (`#13699`).
+- Form Customization wildcards on actions (`#13775`).
+
+## After setup
+
+Confirm manager login (password hash path), Trash Manager, Media Browser sources, and Package Manager purge. If `config.inc.php` looks wrong, restore the pre-upgrade file and re-run setup with a complete 2.7 tree.
+
+If you later move to MODX 3, finish anything that still depends on the deprecated 0.9.x utilities first. See the [MODX 3 upgrade guide](https://docs.modx.com/3.x/en/getting-started/upgrading-to-3.0).

en/getting-started/maintenance/upgrading/2.8.md

@@ -0,0 +1,61 @@
+---
+title: "Upgrading to 2.8"
+sortorder: 89
+---
+
+MODX Revolution 2.8.0 (October 2020) focuses on manager security, file handling, and library updates. Read [the 2.8.2 / 2.8.3 notes](getting-started/maintenance/upgrading/2.8.2) before you install a later 2.8 release.
+
+Release overview: [MODX Revolution 2.8](https://modx.com/blog/modx-revolution-2.8).
+
+## Before you upgrade
+
+- Install the latest 2.8.x patch available. Do not stop at 2.8.0.
+- Update Extras, clear `core/cache`, flush sessions, and back up the database and files.
+- Merge the complete release tree before setup. 2.8.0 fixes a fatal error when upgrading from 2.5.x or earlier, but setup still needs every current core file.
+- List the media sources available to each limited manager user. The new permission checks may remove file access that the user previously had by mistake.
+
+## Security and permissions
+
+2.8.0 closes several manager-side stored XSS issues and hardens file operations:
+
+- Limited manager users can only interact with files in media sources they can access.
+- File upload and file-tree values receive stronger XSS protection.
+- `modRestService` blocks a potential XXE path.
+- Registry messages block path traversal.
+- Template names are escaped in template and TV access grids.
+
+These fixes affect authenticated manager users. Re-test custom manager pages, file browsers, and ACLs with a non-administrator account.
+
+## File and image handling
+
+- `webp` joins the default uploadable file and image types.
+- Upload handling checks whether a file already exists and fixes path selection.
+- The login screen gets responsive styles.
+- phpThumb is updated to 1.7.15.
+
+If you maintain a custom upload allowlist, add `webp` only when the server and your image pipeline support it.
+
+## Template Variables and settings
+
+- URL, RichText, Image, and File TVs gain an **Allow Blank** option.
+- Listbox (Multi-Select) TVs can accept custom values.
+- System Settings gain a number field type.
+
+Review validation for TVs where an empty value must remain forbidden. The new option makes that rule explicit.
+
+## Library updates
+
+2.8.0 updates:
+
+- xPDO to 2.8.1
+- Smarty to 3.1.36
+- PHPMailer to 5.2.28
+- phpThumb to 1.7.15
+
+Test custom Smarty plugins, mail integrations, and image processing after setup.
+
+## After setup
+
+Log in as an administrator and as each limited manager role. Check media source access, uploads, TV validation, resource trash, email delivery, and manager pages supplied by Extras.
+
+Before moving past 2.8.1, read [Upgrading to 2.8.2 and 2.8.3](getting-started/maintenance/upgrading/2.8.2). Those releases tighten static-resource paths and permissions and may require configuration changes.