DOC Add upgrade guide for tractorcow/silverstripe-fluent

[GuySartorelli]

Description from parent issue (since it's private):

Acceptance criteria

• The Guide should explain how to upgrade from Fluent v4 to Fluent v6/v7.
• The Guide should explain how to upgrade from Fluent v5 to Fluent v6/v7.

Notes

• If you are on Fluent v4, we are not sure if the best course of action is to skip 5 and go straight to 6. The person who picks up this card should spend some time analysing what the best approach is on in this case and draft the guide accordingly.

I've opted to make a single upgrade guide that doesn't make assumptions about what version you're upgrading from nor to - though it does state the idea is to adapt your code to be compatible with the latest version.
This means we don't have to duplicate instructions or advice for scenarios where v4 and v5 behave the same way, and both need the same actions taken to upgrade to v6.

There is only one additional consideration for upgrading to v7, which I'll cover in a PR for the CMS 5 changelog. The change is just that FluentExtension::getLinkingMode() and FluentExtension::LocaleLink() are removed in v7. The upgrade guide already notes that they're deprecated and what to use instead, so I think it's fine to not mention v7 here.
I'm explicitly avoiding mention of v7 as that's a CMS 5 consideration, and this upgrade guide is for CMS 4.

After merging

After merging this PR, immediately merge it up to 4 and 5.0. On merge-up to 5.0, delete it, as it isn't applicable for CMS 5 projects (this is the same treatment given to the graphql v3->v4 and phpunit 5=>9 upgrade guides)

Parent issue

• https://github.com/silverstripeltd/product-issues/issues/662

[GuySartorelli]

@mfendeksilverstripe can you please give this a once-over and let me know if I've missed anything or got anything wrong?
CC also @chrispenny and @tractorcow

[chrispenny]

I'd just like to double check: Was it version 5 where it switched to Global? I remembered it being version 6 (but I could certainly be wrong).

[mfendeksilverstripe]

I think it was 5 as Fluent 6 was mostly focused on versioned history stuff.

[GuySartorelli]

I took this from a guide Mojmir created originally, but I decided to run the code examples to validate the results.

In fluent 6.x-dev with global state locale "en_US", with no explicit fallbacks defined and default config:

$result = FluentState::singleton()->withState(function (FluentState $state) {
    $state->setLocale('en_NZ');
    return [
        'titles' => Page::get()->column('Title'),
        'list' => Page::get(),
    ];
});

var_dump([
    $result['titles'], // includes titles from the en_NZ locale
    $result['list']->column('Title'), // includes titles from the en_NZ locale
    Page::get()->column('Title') // includes titles from the en_US locale
]);

Did I do something wrong there? I would have expected only the top result to use en_NZ and the bottom two to use en_US, right?

[chrispenny]

Interesting... Yes, I think I would expect the bottom two to use en_US if we're saying that there is no more local state.

[GuySartorelli]

@mfendeksilverstripe do you have any insight here?

[GuySartorelli]

Removed this section.

[tractorcow]

$result['list']->column('Title'), // includes titles from the en_NZ locale

The query state was set to Fluent.locale = en_NZ when the query was created (i.e. inside the callback). This state persists after the callback is returned. Read queries are always sticky to the locale when they were created, not when they are executed.

[tractorcow]

Interesting... Yes, I think I would expect the bottom two to use en_US if we're saying that there is no more local state.

This should apply to fluent 7 on silverstripe 5; I'll leave this to you to figure out as I'm not using ss 5 :)

[tractorcow]

Still local on fluent 6.

https://github.com/tractorcow-farm/silverstripe-fluent/blob/6/src/Extension/Traits/FluentObjectTrait.php#L75-L83

[tractorcow]

FYI write queries are NOT sticky, and are always in the global locale, and always have been. :)

[mfendeksilverstripe]

Very nice guide 👍

[emteknetnz]

Suggested change

	This documents some of the breaking and functional changes across these three major release lines of the fluent module, as well as some some key things to look out for and general guidelines on how to adapt your code to be compatible with the latest version.
	This documents some of the breaking and functional changes across these three major release lines of the fluent module, as well as some key things to look out for and general guidelines on how to adapt your code to be compatible with the latest version.

[GuySartorelli]

Done

[emteknetnz]

Suggested change

	Fluent 5 introduced some new configurable UI actions, including a new `Localisation` tab in the edit form for localised models where you see and manage the localisation status of each record. The `Localisation` tab is referred in documentation as the "localisation manager".
	Fluent 5 introduced some new configurable UI actions, including a new `Localisation` tab in the edit form for localised models where you see and manage the localisation status of each record. The `Localisation` tab is referred to in documentation as the "localisation manager".

[GuySartorelli]

Done

[emteknetnz]

Suggested change

	As mentioned in the table above, the `batch_actions_enabled` configuration value controls whether a new "Localisation" action group appears in the edit form. This is not to be confused with "batch actions" menu in the site tree.
	As mentioned in the table above, the `batch_actions_enabled` configuration value controls whether a new "Localisation" action group appears in the edit form. This is not to be confused with the "batch actions" menu in the site tree.

[GuySartorelli]

Done