Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOC Update change log to reference updated migration task #8945

Merged
merged 2 commits into from
Apr 29, 2019
Merged

DOC Update change log to reference updated migration task #8945

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a76b53
DOC Update change log to reference updated migration task
Apr 29, 2019
83c2668
Update docs/en/04_Changelogs/4.4.0.md
chillu Apr 29, 2019
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
73 changes: 42 additions & 31 deletions docs/en/04_Changelogs/4.4.0.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/)
Expand All @@ -34,35 +55,14 @@ 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
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?
Expand All @@ -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`
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The point here was to describe the location of the file on the filesystem, not the different virtual or physical paths which get redirected. Those are two different pieces of info, you can't replace one with the other

* 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).
Expand All @@ -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?

Expand Down Expand Up @@ -120,21 +126,26 @@ 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If that second part is true, the first part is redundant (there are no tradeoffs?)

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?

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)
Expand Down