diff --git a/docs/en/04_Changelogs/4.4.0.md b/docs/en/04_Changelogs/4.4.0.md index 0061c58e6..a237b19f9 100644 --- a/docs/en/04_Changelogs/4.4.0.md +++ b/docs/en/04_Changelogs/4.4.0.md @@ -4,7 +4,7 @@ - [Optional migration to hash-less public asset URLs](#hash-less) - [Optional migration of legacy thumbnail locations](#legacy-thumb) - - Security patch for [SS-2018-022](https://www.silverstripe.org/download/security-releases/ss-2018-022) + - Security patch for [CVE-2019-12246](https://www.silverstripe.org/download/security-releases/CVE-2019-12246) - [Correct PHP types are now returned from database queries](/developer_guides/model/sql_select#data-types) - [Upgrade to React 16 in CMS](#upgrade-to-react-16-in-cms) - [Server Requirements](/getting_started/server_requirements/#web-server-software-requirements) have been refined: @@ -14,7 +14,7 @@ - dev/build is now non-destructive for all Enums, not just ClassNames. This means your data won't be lost if you're switching between versions, but watch out for code that breaks when it sees an unrecognised value! - Removed `File.migrate_legacy_file` config option. Migration tasks now need to run via `dev/tasks/`, running them as part of `dev/build` is no longer supported - - [Added navigation and new record actions](#better-buttons) to grid field detail forms. Inspired by @unclecheese's + - [Added navigation and new record actions](#better-buttons) to grid field detail forms. Inspired by @unclecheese's "better buttons". @@ -43,7 +43,7 @@ You’ll want to use the 4.4.1 release if you’re migrating files from SilverSt ### Adopting to new `_resources` directory The name of the directory where vendor module resources are exposed can now be configured by defining a `extra.resources-dir` key in your `composer.json` file. If the key is not set, it will automatically default to `resources`. New projects will be preset to `_resources`. -This will avoid potential conflict with SiteTree URL Segments. +This will avoid potential conflict with SiteTree URL Segments. 1. Update your `.gitignore` file to ignore the new `_resources` directory. This file is typically located in the root of your project or in the `public` folder. 2. Add a new `extra.resources-dir` key to your composer file. @@ -73,7 +73,7 @@ We have ironed out some edge cases since then: * [Remove artifacts from "secureassets" module](#secureassets) * [HTMLText short code migration](#tagtoshortcode) - + You can opt-in to performing these migration tasks on your already upgraded SilverStripe 4.x project. Projects which are upgraded from 3.x to 4.4 or newer will run these tasks by default. You can perform these tasks in the background without CLI access by installing and configuring @@ -90,7 +90,7 @@ The hash would be updated when file contents change, and any link generated through SilverStripe (e.g. through `HTMLText` or `$Image` template placeholders) would automatically adjust. However, any direct links from search engines, bookmarks, etc would break. This limitation was pointed out in the [upgrading advice](4.0.0#asset-storage) to developers, -but the impact wasn’t sufficiently highlighted. +but the impact wasn’t sufficiently highlighted. SilverStripe 4.3.2 introduced a redirect to fix those broken links. Dynamic redirects are more resource intensive than serving static files. @@ -101,7 +101,7 @@ In order to opt-in to moving these files, run the following command: ``` vendor/bin/sake dev/tasks/MigrateFileTask -``` +``` Further information is provided in the [Hash-less Public Asset URLs FAQ](#hashless-faq) below, as well as the [Github issue](https://github.com/silverstripe/silverstripe-versioned/issues/177). @@ -126,7 +126,7 @@ vendor/bin/sake dev/tasks/MigrateFileTask only=move-thumbnails Note that as part of the [hash-less public asset URLs](#hash-less) introduced in this release, requests to these legacy thumbnails will automatically redirect to their new locations. Review the [Github issue](https://github.com/silverstripe/silverstripe-assets/issues/235) -for more details. +for more details. ### Optional migration tasks: Remove artifacts from "secureassets" module {#secureassets} @@ -147,7 +147,7 @@ vendor/bin/sake dev/tasks/MigrateFileTask only=fix-secureassets The task will auto-detect if you have any custom `.htaccess` files in folders, and retain those. Note that you'll need to run your own migration scripts if you've used the module -with IIS and `web.config` files instead. +with IIS and `web.config` files instead. ### Optional migration tasks: HTMLText Shortcode Migration {#tagtoshortcode} @@ -157,7 +157,7 @@ After running the file migration, you can run the short code migration task to u ```bash vendor/bin/sake dev/tasks/TagsToShortcode -``` +``` This will rewrite your existing shortcodes to the newer format SilverStripe 4 expects as well as convert `img` and `a` tags to use shortcodes. @@ -174,7 +174,7 @@ Here's an example of how file names changed during an initial 4.x migration, and * File with hotfix applied (SS 4.2.3): `assets/myfile.pdf` and `assets/[old-content-hash]/myfile.pdf` redirects to `assets/[new-content-hash]/myfile.pdf` * File with full fix applied (SS 4.3.x) : `assets/myfile.pdf` and `assets/[old-content-hash]/myfile.pdf` redirects to `assets/[new-content-hash]/myfile.pdf` * Newly uploaded file with full fix applied (SS 4.4.0): `assets/my-other-file.pdf` (no redirect required) - + More details on how files are stored can be found in the ["File Storage" guide](/developer_guides/files/file_storage). @@ -191,7 +191,7 @@ in your webserver (e.g. through `.htaccess`). The redirect code can be configured via `FlysystemAssetStore.permanent_redirect_response_code`. -If you upgrade an older SilverStripe 4 project to SilverStripe 4.4 and choose not to run the file migration task, +If you upgrade an older SilverStripe 4 project to SilverStripe 4.4 and choose not to run the file migration task, your files will still be stored under a "hash" folder. Browsers who try to access this file via the "hashless" url will be redirected to the "hash" URL with a `302 Temporary Redirect`. @@ -208,7 +208,7 @@ this content is often cached (e.g. in a CDN). We have implemented an automatic redirect for URLs pointing to asset locations prior to running the optional migration script, so there is no need to regenerate any content. - + #### Are there any data loss or data integrity issues? There are no known issues around data integrity. @@ -216,7 +216,7 @@ All files that were available on a SS 3.x site are still available after upgradi #### Will this affect my search engine ranking? -As long as your files are still linked on your website, +As long as your files are still linked on your website, search engines will pick up the new links on any projects which have already been migrated. The 4.3.2 bugfix will redirect links, which passes on any SEO rankings to the new link location. Since links to files should be permanent after the bugfix has been applied, @@ -224,15 +224,15 @@ this can lead to improved search engine rankings (since existing files under new #### Can I migrate away from the legacy_filenames=true option? -Yes. Simply disable `legacy_filenames` in your YML configuration, then run the `MigrateFileTask`. This will normalise +Yes. Simply disable `legacy_filenames` in your YML configuration, then run the `MigrateFileTask`. This will normalise the path of all existing assets. #### Can I still choose legacy_filenames=true when starting new upgrades? -Technically yes, but you need to be aware of the tradeoffs. Once the regression has been fixed, we don’t see the need +Technically yes, but you need to be aware of the tradeoffs. Once the regression has been fixed, we don’t see the need for people to choose this option any more. -SilverStripe 4.4, ignores `legacy_filenames` in most situations. Enabling `legacy_filenames` on a fresh SilverStripe +SilverStripe 4.4, ignores `legacy_filenames` in most situations. Enabling `legacy_filenames` on a fresh SilverStripe 4.4 installation will have no affect. #### How do I test that the fix has worked on my site? @@ -242,12 +242,12 @@ Find an existing published and draft file. Get the link by clicking on the previ It should link to `assets/[hash]/myfile.pdf`. After applying the upgrade and migration task, you can test that it applied correctly. -Please perform these tests on a test or UAT environment, since your local environment might have different routing +Please perform these tests on a test or UAT environment, since your local environment might have different routing conditions. * Check that the file still routes correctly with the hash in place (should redirect) * Remove `[hash]/`, and check that it still routes correctly (should not redirect) - + #### Will this patch redirect URLs for previous file versions? Yes, it will attempt to find the most recent public "hash-less" URL @@ -333,7 +333,7 @@ If you have thirdparty code, such as a backend module, that depends on React UIs ### DevelopmentAdmin controllers -The security fix for [SS-2018-022](https://www.silverstripe.org/download/security-releases/ss-2018-022) introduces a new +The security fix for [CVE-2019-12246](https://www.silverstripe.org/download/security-releases/CVE-2019-12246) introduces a new [Confirmation](api:SilverStripe\Security\Confirmation) component and [ConfirmationMiddleware](api:SilverStripe\Control\Middleware\ConfirmationMiddleware) that prevents CSRF based attacks on the urls placed under `dev/*` path. @@ -385,9 +385,9 @@ The best practice is not to reuse the application manifest cache between deploys ### New GridField detail form actions {#better-buttons} -Pagination controls and an add new button has been added to the bottom toolbar of GridField detail forms. This is +Pagination controls and an add new button has been added to the bottom toolbar of GridField detail forms. This is enabled by default. In cases where you do not want these buttons to appear on your detail form then you can use the new -[constructor API](http://api.silverstripe.com/4/SilverStripe/Forms/GridField/GridFieldDetailForm.html#method___construct) +[constructor API](http://api.silverstripe.com/4/SilverStripe/Forms/GridField/GridFieldDetailForm.html#method___construct) of the detail form to control whether pagination and/or the add button are shown. Additionally the default value can be set globally with the following configuration: