tonyair/silverstripe-framework
1
0
Fork 0
mirror of https://github.com/silverstripe/silverstripe-framework synced 2024-06-26 06:29:24 +02:00
Code Issues Projects Releases Wiki Activity

DOC Update change log to reference updated migration task (#8945)

Browse Source 
* DOC Update change log to reference updated migration task

* Update docs/en/04_Changelogs/4.4.0.md
This commit is contained in:
Maxime Rainville 2019-04-30 08:45:30 +12:00 committed by Ingo Schommer
parent 4155b9f483
commit 54cb591f54
1 changed files with 42 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

73
docs/en/04_Changelogs/4.4.0.md
View File

@ -11,6 +11,27 @@
## Upgrading {#upgrading}
### 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.
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.
```js
{
// ...
"extra": {
// ...
"resources-dir": "_resources"
}
}
```
3. Expose your vendor assets by running `composer vendor-expose`.
4. Remove the old `resources` folder. This folder will be located in the `public` folder if you have adopted the public web root, or in the root of your project if you haven't.
You may also need to update your server configuration if you have applied special conditions to the `resources` path.
### Optional migration to hash-less public asset URLs {#hashless-urls}
SilverStripe 4.x introduced an [asset abstraction](https://docs.silverstripe.org/en/4/developer_guides/files/file_storage/)
@ -34,7 +55,7 @@ The original "hashed" file paths continue to work through redirects.
In order to opt-in to moving these files, run the following command:
```
TODO File migration task command
vendor/bin/sake dev/tasks/MigrateFileTask
```
Note that you can run this task without CLI access by installing and configuring
@ -42,27 +63,6 @@ the [queuedjobs](https://github.com/symbiote/silverstripe-queuedjobs) module.
Further information is provided in the [Hash-less Public Asset URLs FAQ](#hashless-faq) below.
### 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.
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.
```js
{
// ...
"extra": {
// ...
"resources-dir": "_resources"
}
}
```
3. Expose your vendor assets by running `composer vendor-expose`.
4. Remove the old `resources` folder. This folder will be located in the `public` folder if you have adopted the public web root, or in the root of your project if you haven't.
You may also need to update your server configuration if you have applied special conditions to the `resources` path.
### Hash-less Public Asset URLs FAQ {#hashless-faq}
#### How are files named and renamed?
@ -73,9 +73,9 @@ Here's an example of how file names changed during an initial 4.x migration, and
* File migrated under SS 4.x with `legacy_filenames=false`: `assets/[content-hash]/myfile.pdf` (Regression: links to `assets/myfile.pdf` no longer work)
* File migrated under SS 4.x with `legacy_filenames=true`: `assets/myfile.pdf`
* File with updated file content under SS 4.x: `assets/[new-content-hash]/myfile.pdf` (Regression: links to `assets/[content-hash]/myfile.pdf` no longer work)
* File with hotfix applied (SS 4.2.3): `assets/[new-content-hash]/myfile.pdf` (redirects to `assets/myfile.pdf`)
* File with full fix applied (SS 4.3.x) : `assets/myfile.pdf` (no redirect required)
* Newly uploaded file with full fix applied: `assets/my-other-file.pdf` (no redirect required)
* 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).
@ -91,7 +91,13 @@ If you have a high traffic site with lots of direct references to asset URLs
we recommend that you configure HTTP caching for these redirects
in your webserver (e.g. through `.htaccess`).
The redirect code can be configured via `FlysystemAssetStore.redirect_response_code`.
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,
your files will still be stored under an "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`.
The temporary redirect code can be configured via `FlysystemAssetStore.redirect_response_code`.
#### Do I need to regenerate HTML with existing links to assets?
@ -120,12 +126,16 @@ this can lead to improved search engine rankings (since existing files under new
#### Can I migrate away from the legacy_filenames=true option?
Technically yes, but there’s no official migration script for it.
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 for people to choose this option any more.
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 the `legacy_filenames` in most situation. 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?
@ -133,8 +143,9 @@ Before applying the upgrade and migration script:
Find an existing published and draft file. Get the link by clicking on the preview in `admin/assets`.
It should link to `assets/[hash]/myfile.pdf`.
After applying the upgrade and migration script, 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 conditions.
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
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)