From dc5f2932a184d3f7add70470eee57982381c7669 Mon Sep 17 00:00:00 2001 From: Fernando Schubert Date: Mon, 16 Nov 2026 11:42:23 -0300 Subject: [PATCH] Add v29 upgrade guide and compatibility chart row (cherry picked from commit fb662cdaefb3bb604324a2e51e6c7ec5937b55ac) --- other-docs/guides/updating-php/README.md | 2 +- other-docs/guides/upgrading/README.md | 1 + other-docs/guides/upgrading/v29.md | 122 +++++++++++++++++++++++ 3 files changed, 124 insertions(+), 1 deletion(-) create mode 100644 other-docs/guides/upgrading/v29.md diff --git a/other-docs/guides/updating-php/README.md b/other-docs/guides/updating-php/README.md index e170719b..9291b78d 100644 --- a/other-docs/guides/updating-php/README.md +++ b/other-docs/guides/updating-php/README.md @@ -12,10 +12,10 @@ There are 2 key steps to getting ready for a new version of PHP: | Altis | PHP 8.5 | PHP 8.4 | PHP 8.3 | PHP 8.2 | PHP 8.1 | |-------|---------------|---------------|---------------|---------------|---------------| +| v29 | **Supported** | **Supported** | **Supported** | | | | v28 | **Supported** | **Supported** | **Supported** | *Deprecated* | | | v27 | **Supported** | **Supported** | **Supported** | *Deprecated* | | | v26 | | **Supported** | **Supported** | *Deprecated* | *Deprecated* | -| v25 | | **Supported** | **Supported** | *Deprecated* | *Deprecated* | ## Checking PHP Version Compatibility diff --git a/other-docs/guides/upgrading/README.md b/other-docs/guides/upgrading/README.md index e7b0cbc3..1404ea7e 100644 --- a/other-docs/guides/upgrading/README.md +++ b/other-docs/guides/upgrading/README.md @@ -43,6 +43,7 @@ with "BREAKING: " in the version release notes. ## Upgrade Guides +- [Version 29](./v29.md) - [Version 28](./v28.md) - [Version 27](./v27.md) - [Version 26](./v26.md) diff --git a/other-docs/guides/upgrading/v29.md b/other-docs/guides/upgrading/v29.md new file mode 100644 index 00000000..617d290b --- /dev/null +++ b/other-docs/guides/upgrading/v29.md @@ -0,0 +1,122 @@ +--- +order: 29 +--- + +# Upgrading to v29 + +*If you are migrating from WordPress to Altis, check out the [migrating guide](../migrating/) first.* + +To upgrade to Altis v29, edit your `composer.json` and change the version constraint for `altis/altis` and any local environment +modules to `^29.0.0`. + +```json +{ + "require": { + "altis/altis": "^29.0.0" + }, + "require-dev": { + "altis/local-server": "^29.0.0" + }, + "config": { + "platform": { + "php": "8.4" + } + } +} +``` + +Once you have made these changes, run `composer update` and then run the `wp altis migrate` command: + +```sh +# For cloud environments +wp altis migrate + +# For local server +composer server cli -- altis migrate +``` + +## PHP 8.2 Is No Longer Supported + +Altis v29 supports PHP 8.3, 8.4 and 8.5. PHP 8.2 is no longer supported. + +If your environments still run PHP 8.2, upgrade them to PHP 8.3 or later as part of this upgrade. The +[updating PHP guide](../updating-php/) explains how to check your code for compatibility and how to switch the PHP version of +your environments. The [Altis compatibility chart](../updating-php/#altis-compatibility-chart) lists the PHP versions +supported by each Altis version. + +Update the `config.platform.php` setting in your `composer.json` to the PHP version your environments run, so Composer +installs dependencies that are compatible with it. + +## Stream: Secrets No Longer Written to the Activity Log + +Stream (the secure audit log) is updated to 4.4.0. Earlier versions could write secret values to the activity log in clear +text when certain settings were changed. These included WooCommerce and EDD payment gateway and webhook keys, Gravity +Forms licence and reCAPTCHA keys, Jetpack connection tokens, and the mailbox password (`mailserver_pass`). Stream now +replaces such values with `[redacted]`. + +Only new records are protected. Entries written by earlier versions are not changed and may still contain secrets. + +### Do You Need to Act? + +Users who can already view these settings could read these values without the log, so their access to the log exposed +nothing new. + +You should act if either of these is true: + +- Users with access to the Stream log, but without access to these settings, could read the log. +- Log records were exported or forwarded to another system. + +In that case, rotate the affected credentials. Deleting the log entries is not an option because Altis keeps these audit +logs in a write-only system. For each affected credential: + +1. Replace the value at the provider and revoke the old one. Examples are the payment gateway key, the webhook secret, the + Jetpack connection and the mailbox password. +2. Check the provider's access logs for use of the old value from unexpected locations. +3. Restrict access to any exported copies of the log. + +If you're unsure whether a value was exposed, assume it was. + +## Headline Features + +### Instructions for AI Coding Agents + +New Altis projects now include an `AGENTS.md` file, which gives AI coding agents an overview of an Altis project: what it +is, how to run Local Server and the tests, and common pitfalls. A `CLAUDE.md` file is also included. It only loads +`AGENTS.md`, so there is a single file to maintain. + +These files are part of the [Altis skeleton](https://github.com/humanmade/altis-skeleton), which is only copied when a +project is created, so upgrading an existing project does not add them. To use them in an existing project, copy +[`AGENTS.md`](https://github.com/humanmade/altis-skeleton/blob/v29-branch/AGENTS.md) and +[`CLAUDE.md`](https://github.com/humanmade/altis-skeleton/blob/v29-branch/CLAUDE.md) into your project root. + +The files are a starting point. Edit them and add your own project's notes, such as its structure, coding standards and +how to run its tests. Your copy is not updated by later Altis releases, so check the skeleton when you upgrade if you +want to pick up improvements. + +### Altis Dashboard Features + +- **User-agent allowlist**: [User-Agent Access Control](docs://cloud/WAF/ua-access-control/#allowlist) now has an + allowlist, so you can let specific clients through rules that would otherwise block them. +- **Copy traffic settings between environments**: Traffic Management settings can be copied from one environment to + another, so you can test a configuration on staging and then apply it to production. +- **Log Insights**: the new [Log Insights](docs://cloud/dashboard/x-ray/#log-insights) page under X-Ray groups similar + lines from your PHP and Nginx error logs and lists the most frequent groups first, so you can see which errors happen + most often without reading every line. +- **Cancel and retry builds**: you can cancel a build that is in progress, and retry a failed build with one click. + +### Altis Local Server Improvements + +- **Elasticsearch memory**: `ES_MEM_LIMIT` now sets the total memory of the Elasticsearch container, and Local Server + gives 50% of it to the Elasticsearch heap. Previously the same value was used for both the container and the heap, which + left no room for anything else and could get Elasticsearch killed when working with large indexes. If you set + `ES_MEM_LIMIT` to size the heap, double it to keep the same heap size. See the + [Elasticsearch configuration documentation](docs://enhanced-search/configuration/) for details. + +### Altis Core Improvements + +We have incorporated many updates to modules and libraries in Altis to bring in important bug fixes and improvements. + +### Documentation + +Our developer focused documentation has been improved again. As usual, feedback from our customers and partners is always welcome. +Please [send us any feedback you have](support://new).