Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion other-docs/guides/updating-php/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down
1 change: 1 addition & 0 deletions other-docs/guides/upgrading/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
122 changes: 122 additions & 0 deletions other-docs/guides/upgrading/v29.md
Original file line number Diff line number Diff line change
@@ -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).
Loading