From 26c540e266e5f6e50826a5b1d1a0053ff2738210 Mon Sep 17 00:00:00 2001 From: Robert O'Rourke Date: Wed, 6 Jan 2021 18:20:02 +0000 Subject: [PATCH] Add v6 upgrade guide --- other-docs/guides/upgrading/README.md | 6 ++ other-docs/guides/upgrading/v6.md | 110 ++++++++++++++++++++++++++ 2 files changed, 116 insertions(+) create mode 100644 other-docs/guides/upgrading/v6.md diff --git a/other-docs/guides/upgrading/README.md b/other-docs/guides/upgrading/README.md index 4cd3d7ce..5c69a034 100644 --- a/other-docs/guides/upgrading/README.md +++ b/other-docs/guides/upgrading/README.md @@ -1,3 +1,7 @@ +--- +order: 0 +--- + # Upgrading _If you are migrating an existing install to Altis check out the [migrating guide here](../migrating-from-wordpress.md) first._ @@ -31,6 +35,8 @@ Any upgrade will usually require some modification to your project (for example, ## Upgrade Guides +- [Version 6](./v6.md) +- [Version 5](./v5.md) - [Version 4](./v4.md) - [Version 3](./v3.md) - [Version 2](./v2.md) diff --git a/other-docs/guides/upgrading/v6.md b/other-docs/guides/upgrading/v6.md new file mode 100644 index 00000000..2fe94548 --- /dev/null +++ b/other-docs/guides/upgrading/v6.md @@ -0,0 +1,110 @@ +# Upgrading to v6 + +_If you are migrating from WordPress to Altis, check out the [migrating guide here](../migrating-from-wordpress.md) first._ + +To upgrade to Altis v6, edit your `composer.json` and change the version constraint for `altis/altis` and any local environment modules to `^6.0.0`: + +```json +{ + "require": { + "altis/altis": "^6.0.0" + }, + "require-dev": { + "altis/local-chassis": "^6.0.0", + "altis/local-server": "^6.0.0" + } +} +``` + +Next remove the `vendor` directory by running `rm -rf vendor` or on Windows `rmdir vendor`. You could also delete the directory using your code editor, Finder or Explorer. + +**Note:** due to an issue in how Composer handles installation of `composer-plugin` packages the above step is required to ensure the new version of the required packages are used to manage the process. + +Next run `composer update` to complete the upgrade. You should commit the updated `composer.json` and `composer.lock` files. + +You will need to update your database tables using the CLI: + +- On [Altis Dashboard](https://dashboard.altis-dxp.com/) find the stack you have deployed to and run `core update-db --network` (`wp` is automatically prepended) in the WP CLI tab +- For Local Chassis run `composer chassis exec -- wp core update-db --network` +- For Local Server run `composer local-server cli -- core update-db --network` + +There is also a Cavalcade database update to improve performance: + +- On [Altis Dashboard](https://dashboard.altis-dxp.com/) find the stack you have deployed to and run `cavalcade upgrade` (`wp` is automatically prepended) in the WP CLI tab +- For Local Chassis run `composer chassis exec -- wp cavalcade upgrade` +- For Local Server run `composer local-server cli -- cavalcade upgrade` + +If you use Local Chassis you will need to also update Chassis and its extensions by running `composer chassis upgrade`. + + +## Breaking Changes + +### jQuery Updated to 3.5.1 + +If you find issues relating to jQuery in the JavaScript console you can try installing the [jQuery Migrate plugin](https://wordpress.org/plugins/enable-jquery-migrate-helper/) as a short term solution. It is advisable to make sure all of your dependencies are up to date and that any custom code is compatible with jQuery v3 if used. + +### Block Editor + +The Resuable Blocks API [has been moved from the `@wordpress/editor` package to its own package under `@wordpress/reusable-blocks`](https://make.wordpress.org/core/2020/11/18/reusable-blocks-extracted-into-a-separate-package/). + +There are [editor styling changes](https://make.wordpress.org/core/2020/11/18/editor-styling-changes-in-wordpress-5-6/), notably block style font sizes now use relative units (`em`) for sizing so you may see some inconsistent styling in custom block UIs. + +[The `` component should no longer be nested to group sets of controls](https://make.wordpress.org/core/2020/11/18/changes-to-toolbar-components-in-wordpress-5-6/). In addition there are new `` and `` components that should be used as the only direct children of the `` or `` components. + +### Local Server and Local Chassis PHP Version + +Local Server and Local Chassis are both now using PHP 7.4. The [full list of backwards incompatibilities can be found here](https://www.php.net/manual/en/migration74.incompatible.php). + + +## Headline Features + +### Altis Privacy Module + +The brand new [Altis Privacy Module](docs://privacy/README.md) is the new home for all core functionality related to protecting your users' privacy. + +The key highlights are: + +* A robust and highly extensible Cookie Consent API +* Built in cookie consent banner +* Out of the box integration with Altis Analytics and Google Tag Manager + +### WordPress 5.6 "Simone" + +The latest CMS module includes WordPress 5.6. Some of the highlights of this release are: + +* [Application Passwords](https://make.wordpress.org/core/2020/11/05/application-passwords-integration-guide/) make it easy to create tokens that can be used to make authenticated API requests using HTTP Basic Auth. The tokens cannot be used to log in to WordPress so provide a more secure way to interact with the API. +* [Block API v2](https://make.wordpress.org/core/2020/11/18/block-api-version-2/) makes blocks more self contained by allowing for custom block wrapper components along with many other improvements. +* The [REST API Batch Framework](https://make.wordpress.org/core/2020/11/20/rest-api-batch-framework-in-wordpress-5-6/) makes it possible to combine the results from multiple API endpoints into a single request. + +You can [find the full WordPress 5.6 release notes here](https://wordpress.org/news/2020/12/simone/), and the developer [field guide here](https://make.wordpress.org/core/2020/11/20/wordpress-5-6-field-guide/). Some internal APIs and compatibility may have changed, especially in block editor APIs, so ensure you consult the field guide for a full list of changes. + +Note that in line with our development and user experience philosophies, some changes in the CMS module may differ from WordPress changes. Notably one of the major features in WordPress 5.6 is in the autoupdate system, which is disabled in Altis. + +### Experience Block Analytics + +Experience Blocks now support setting conversion goals allowing you to see how well your personalized content is performing. Out of the box the following conversion goals are supported: + +- Impressions, the percentage of page views a block appears on where the block was visible in the browser viewport +- Clicking any link in the Experience Block's content +- Submitting a form + +Custom conversion goals can also be registered in PHP or JavaScript. + + +## Other Features and APIs + +### Analytics Data Export + +A [new REST API endpoint has been added to enable downloading analytics in JSON or CSV format](docs://analytics/native/data-export.md). This works well in conjunction with the new Application Passwords feature. + +### Composer v2 Support + +Altis is now fully compatible with Composer version 2. + +### Development Environments + +Local Chassis and Local Server have been updated to use PHP 7.4. + +### Other Changes + +Altis v6 includes many other small changes, consult the changelog for full details of all the changes shipped in this release.