Skip to content

Commit

Permalink
Merge pull request #568 from humanmade/backport-567-to-v19-branch
Browse files Browse the repository at this point in the history 
[Backport v19-branch] v19 Beta prep
  • Loading branch information
@mikelittle
mikelittle authored Apr 22, 2024
2 parents 33e574e + dd5923c commit 63dfaf4
Show file tree
Hide file tree
Showing 3 changed files with 136 additions and 32 deletions.
60 changes: 36 additions & 24 deletions other-docs/guides/updating-php/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
# Updating PHP Version

On occasion Altis will make a PHP version update available. Once a particular version of PHP is out of support, updating to a later version will become mandatory to help protect the security of your application.
On occasion Altis will make a PHP version update available. Once a particular version of PHP is out of support, updating
to a later version will become mandatory to help protect the security of your application.

There are 2 key steps to getting ready for a new version of PHP:

Expand All @@ -9,51 +10,52 @@ There are 2 key steps to getting ready for a new version of PHP:

## Altis Compatibility Chart


| Altis | PHP 8.0 | PHP 8.1 | PHP 8.2 |
|-------|----------------|---------------|----------------|
| v19 | | **Supported** | *Supported* |
| v18 | **Deprecated** | **Supported** | *Supported* |
| v17 | **Deprecated** | **Supported** | *Experimental* |
| v16 | **Deprecated** | **Supported** | *Experimental* |
| v15 | **Deprecated** | **Supported** | *Experimental* |
| v14 | **Deprecated** | **Supported** | |


## Checking PHP Version Compatibility

**Note:** Before carrying out the following tasks locally, ensure your application is fully installed so that all code that will be deployed to the cloud is present.
**Note:** Before carrying out the following tasks locally, ensure your application is fully installed so that all code
that will be deployed to the cloud is present.

### Switch Off Composer's Platform Check

In your `composer.json` you may have some code like the following:

```json
{
"config": {
"platform": {
"php": "8.1"
}
}
"config": {
"platform": {
"php": "8.1"
}
}
}
```

If present, and the PHP version does not match the version you are upgrading to you should update it to reflect the new target PHP version.
If present, and the PHP version does not match the version you are upgrading to you should update it to reflect the new
target PHP version.

In addition you _must_ add the following setting in the `config` property of your `composer.json` file:

```json
{
"config": {
"platform-check": false
}
"config": {
"platform-check": false
}
}
```

This will prevent Composer from exiting your application early while your cloud environment is being updated.

### Update All Altis Modules

The first task is to ensure your application has the latest patch versions of all Altis modules by running the following command in your project root:
The first task is to ensure your application has the latest patch versions of all Altis modules by running the following
command in your project root:

```
composer update "altis/*" --with-all-dependencies
Expand All @@ -63,7 +65,9 @@ Afterwards commit the updated `composer.lock` file.

### Run The Compatibility Check

The next step is using the PHP Compatibility package for PHP Code Sniffer. The guide belows shows you how to install and use this tool globally, however you may wish to install them directly in your project and use them in CI as part of your code linting process.
The next step is using the PHP Compatibility package for PHP Code Sniffer. The guide belows shows you how to install and
use this tool globally, however you may wish to install them directly in your project and use them in CI as part of your
code linting process.

First install the standard and dependencies using the following command:

Expand All @@ -85,25 +89,32 @@ This can take a long time to run so may wish to run it just in your custom code

**Note:** You _must_ fix anything reported as an "Error". Warnings can be ignored at your discretion.

Fix any reported errors (ignoring those listed in the section below) by upgrading affected third party plugins and amending first party custom code as needed following your standard code review and deployment processes.
Fix any reported errors (ignoring those listed in the section below) by upgrading affected third party plugins and
amending first party custom code as needed following your standard code review and deployment processes.

#### Known Warnings and Errors

There are some known warnings in the following packages that you can safely ignore. Altis guarantees its core packages and their dependencies are verified as working with the versions outlined in the compatibility chart at the top of this page.
There are some known warnings in the following packages that you can safely ignore. Altis guarantees its core packages
and their dependencies are verified as working with the versions outlined in the compatibility chart at the top of this
page.

- `aws/aws-sdk-php`
- `humanmade/batcache`
- `phpunit/phpunit`
- `wp-phpunit/wp-phpunit`
- `lucatume/wp-browser`

You can add these to the ignored directories in the command when checking if desired; e.g. `--ignore=vendor/aws,vendor/guzzlehttp,...`.
You can add these to the ignored directories in the command when checking if desired;
e.g. `--ignore=vendor/aws,vendor/guzzlehttp,...`.

## Requesting A Cloud Environment Update

Once you are confident that your application is compatible with the version of PHP to upgrade to you should do the following for each environment:
Once you are confident that your application is compatible with the version of PHP to upgrade to you should do the
following for each environment:

1. Create a support ticket for the target environment with the type "Task", titled "Upgrade to PHP 8.1", replacing "8.1" with the target version if necessary ( noting that the updated PHP version will not be deployed automatically until the next application deployment ).
1. Create a support ticket for the target environment with the type "Task", titled "Upgrade to PHP 8.1", replacing "8.1"
with the target version if necessary ( noting that the updated PHP version will not be deployed automatically until
the next application deployment ).
2. Wait for the Altis team to confirm the environment has been updated.
3. Deploy the updated application code.

Expand All @@ -115,12 +126,13 @@ The Altis team will follow up with you on the ticket once the environment has be

Once your environment has been upgraded, the PHP upgrade will take effect upon the next application deployment.


## Re-Enable Composer's Platform Check

If you previously disabled the platform check in Composer, you can now re-enable it once everything has been upgraded. Remove the `"platform-check": false` line if you added it.
If you previously disabled the platform check in Composer, you can now re-enable it once everything has been upgraded.
Remove the `"platform-check": false` line if you added it.

Additionally, we recommend setting the PHP version explicitly, which will ensure the correct packages are installed for your PHP version.
Additionally, we recommend setting the PHP version explicitly, which will ensure the correct packages are installed for
your PHP version.

The easiest way to add this is to run:

Expand Down
26 changes: 18 additions & 8 deletions other-docs/guides/upgrading/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,35 +6,45 @@ order: 0

_If you are migrating an existing install to Altis check out the [migrating guide](../migrating/) first._

When new versions of Altis are released you will need to manually upgrade your project to the new version. New versions can bring anything from breaking changes to new features. It's important you read the changelog / upgrade notes for the specific version you are upgrading to. When upgrading multiple versions at once, be sure to follow the release notes on all intermediate versions.
When new versions of Altis are released you will need to manually upgrade your project to the new version. New versions
can bring anything from breaking changes to new features. It's important you read the changelog / upgrade notes for the
specific version you are upgrading to. When upgrading multiple versions at once, be sure to follow the release notes on
all intermediate versions.

To switch the version of Altis for your project, modify the version constraint for the `altis/altis` dependency in your `composer.json`. For example, to upgrade to Altis version 18.
To switch the version of Altis for your project, modify the version constraint for the `altis/altis` dependency in
your `composer.json`. For example, to upgrade to Altis version 19.

```json
{
"name": "company-name/my-site",
"require": {
"altis/altis": "^18.0.0"
"altis/altis": "^19.0.0"
},
"require-dev": {
"altis/local-chassis": "^18.0.0",
"altis/local-server": "^18.0.0"
"altis/local-chassis": "^19.0.0",
"altis/local-server": "^19.0.0"
}
}
```

Next run `rm -rf vendor` on MacOS or Linux, or on Windows `rmdir vendor`.

*Note:* this is due to an issue in how Composer handles installation of `composer-plugin` type packages, and ensures the latest version of the package is used during the upgrade process. We are working to improve this process in future releases.
*Note:* this is due to an issue in how Composer handles installation of `composer-plugin` type packages, and ensures the
latest version of the package is used during the upgrade process. We are working to improve this process in future
releases.

Next, run `composer update` to pull in the latest version of the packages.

This will generate a new `composer.lock` file. Both the `composer.json` and `composer.lock` should be committed to version control, and deployed.
This will generate a new `composer.lock` file. Both the `composer.json` and `composer.lock` should be committed to
version control, and deployed.

Any upgrade will usually require some modification to your project (for example, deprecated APIs, new features you may want to implement). Altis is conservative about breaking backwards compatibility. Any known issues will be prefixed with "BREAKING: " in the version release notes.
Any upgrade will usually require some modification to your project (for example, deprecated APIs, new features you may
want to implement). Altis is conservative about breaking backwards compatibility. Any known issues will be prefixed
with "BREAKING: " in the version release notes.

## Upgrade Guides

- [Version 19](./v19.md)
- [Version 18](./v18.md)
- [Version 17](./v17.md)
- [Version 16](./v16.md)
Expand Down
82 changes: 82 additions & 0 deletions other-docs/guides/upgrading/v19.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
---
order: 19
---

# Upgrading to v19

_If you are migrating from WordPress to Altis, check out
the [migrating guide](../migrating/) first._

To upgrade to Altis v19, edit your `composer.json` and change the version
constraint for `altis/altis` and any local environment modules to `^19.0.0`.

```json
{
"require": {
"altis/altis": "^19.0.0"
},
"require-dev": {
"altis/local-server": "^19.0.0"
},
"config": {
"platform": {
"php": "8.1"
}
}
}
```

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
```

## Breaking Changes

## Changes to the Altis platform

### PHP

PHP 8.1 and 8.2 are our recommended versions of PHP for Altis. Note that there are a small number of exceptions to
Compatibility in the core WordPress CMS module. See the [WordPress
documentation on compatibility](https://make.wordpress.org/core/handbook/references/php-compatibility-and-wordpress-versions/)
for more information.

PHP 8.0 is no longer supported in Altis.

Refer to our [PHP Version Guide](docs://guides/updating-php/) for up-to-date
compatibility, testing and upgrading information.

## Headline Features

### WordPress 6.5.0

WordPress 6.5.0 brings lots of new features, bug fixes, and improvements. There are hundreds of enhancements, new
features, bug fixes, and more. The block editor alone has almost 100 updates. These improvements include:

- Performance and accessibility enhancements,
- Performant Translations,
- Block– and Site–Editor Unification,
- A new Font Library, and design tool enhancements, and
- Support for [AVIF images](https://make.wordpress.org/core/2024/02/23/wordpress-6-5-adds-avif-support/).

See the
[WordPress 6.5 Field Guide](https://make.wordpress.org/core/2024/03/15/wordpress-6-5-field-guide/) for more
information.

There are new and improved features of interest to developers such as:

- The Block Bindings and Interactivity APIs,
- Classic themes and Site Editor updates,
- Native JavaScript module support,
- Plugin dependencies, and more.

### Altis Core improvements

We have incorporated many updates to modules and libraries in Altis to bring in important bug fixes and improvements.

0 comments on commit 63dfaf4

Please sign in to comment.