Restructure CMS 6.0 changelog

[GuySartorelli]

Two commits intentionally - do not squash.

Issue

• Review CMS 6 changelog and docs prior to stable release #689

[GuySartorelli]

Similar to the start of the 5.0.0 changelog

[GuySartorelli]

Moved things that are directly related to changes in supported modules into this section. If you need to add or exclude deps in composer.json, it goes here.

[GuySartorelli]

Moved dependency changes to be directly below the supported modules section, because then we have all the composer.json stuff packed together.

[GuySartorelli]

These feel like they belong in dependency changes since they're stuff you deal with before you start diving into actual code

[GuySartorelli]

1. Removed "Elemental TopPage class names changed" section and put that content straight into "Many renamed classes".
2. Moved "changes to some extension hook names" right under "Many renamed classes" so the renaming stuff is grouped
3. Moved "Changes to the templating/view layer" and "Changes to LeftAndMain and its subclasses" into the API changes section because they're more about changes to the API than they are about functional enhancements

[GuySartorelli]

1. Renamed "Other changes" to "Breaking changes" so it was clearer what sort of thing is in here. I've also added a paragraph to the start of the section indicating the scope of the section
2. Moved to be inbetween "Features and enhancements" and "Bug fixes" mostly to get it out from under "API changes". I want "API changes" to be right above the "Full list of removed and changed API" since that's API with API.
3. "$CurrentPageURL template support removed" section removed - it's just a bullet point under "API changes > general changes" now.
4. Moved "Changes to scaffolded form fields" and "SiteTree uses form field scaffolding" into here because these are kinda miscellaneous-feeling breaking changes.
5. Moved "Run CanonicalURLMiddleware in all environments by default" here because it's not really an enhancement, but it is a breaking change

[emteknetnz]

I don't think "Breaking changes" is helpful here, because we have "API changes" as well which are also breaking. It implies that the API changes are not breaking, when they are.

I think "Other changes" is better.

[GuySartorelli]

I added a blurb to the section to help alleviate that confusion - but how about "Other breaking changes"? That's what we used in CMS 5.

I don't like just "Other changes" because it sounds like the stuff in there is less important than the rest of the changelog.

[emteknetnz]

We did all these things to make things better right? So they're basically all enhancements, it's just they happen to be breaking

Maybe just list them under the "Features and enhancements" section?

[GuySartorelli]

Yeah that makes sense I guess. I was originally trying to keep some separation between the not-so-breaking things and the "these are just plain breaking changes" things. But any distinction here will have exceptions no matter how you try to cut it. I have no qualms with combining them.

[GuySartorelli]

1. Moved validation next to validation
2. Added "and" to "Changes to sake, BuildTask, and CLI interaction in general" to match actual heading

[GuySartorelli]

Separated this out from "Changes to the templating/view layer" because these are enhancements that aren't really related to the whole separation of view vs model.

[GuySartorelli]

Added emphasis to the main breaking change by moving to the top and saying what the default used to be

[emteknetnz]

Seems like the PR is mostly about just reordering existing content without changing much of it. I'm basing this of the number of lines added and removed being fairly close when accounting for the CMS 5 changelogs being removed.

I feel the changelog in this PR reads somewhat negatively, because at the top it has several "things that are going away" e.g. modules loosing commercial support.

I think the changelog should lead with "new features" which is what people will be most looking forward to seeing. As much as we go on about "majors are for breaking changes", people are always asking about "what new features are in CMS 6", so we may as well arrange things to meet other peoples expectations.

Here's an alternative arrangement:

Note that within "Change to commercially supported modules" I've reoorded things so that the "new" stuff is up the top and the "going away" stuff is down the bottom

- Features and enhancements
    - Validation added to DBFields
    - Changes to password validation
    - Changes to sake, BuildTask, and CLI interaction in general
    - Read-only replica database support
    - Improvements to template functionality
    - Performance improvements for site tree rendering
    - Changes to default cache adapters
    - Filter within a range with searchable_fields
    - Status flags in the CMS
    - New Versioned methods
    - Other new features
- Other changes
    - Changes to scaffolded form fields
    - SiteTree uses form field scaffolding
    - MySQL now defaults to utf8mb4
    - Run CanonicalURLMiddleware in all environments by default
    - Session and authentication cookie changes
    - DBDecimal default value
    - RedirectorPage validation
    - Update JS MIME type, remove type in <script> tags
    - getSchemaDataDefaults() now includes attributes
    - Remember me token rotation
- Change to commercially supported modules
    - New supported modules
    - New default front-end theme
    - TinyMCE is in a separate module now
    - silverstripe/campaign-admin no longer part of silverstripe/recipe-cms
    - Modules losing commercial support
- Dependency changes
    - PHP version support
    - MySQL 5 no longer supported
    - intervention/image has been upgraded from v2 to v3
    - symfony dependencies have been upgraded from v6 to v7
    - JavaScript dependencies
- Upgrade tools
- Bug fixes
- API changes
    - Many renamed classes
    - Changes to some extension hook names
    - GraphQL removed from the CMS
    - Changes to the templating/view layer
    - Changes to LeftAndMain and its subclasses
    - FormField classes now use FieldValidator for validation
    - CMSMain search filter changes
    - Most extension hook methods are now protected
    - FormField::Value() split into two methods
    - Controller::has_curr() removed
    - Strict typing for Factory implementations
    - List interface changes
    - General changes
- Full list of removed and changed API (by module, alphabetically)

[emteknetnz]

Suggested change

	- [Change to commercially supported modules](#changes-to-support)
	- [Changes to commercially supported modules](#changes-to-support)

[GuySartorelli]

Done, good catch

[emteknetnz]

I don't think "Breaking changes" is helpful here, because we have "API changes" as well which are also breaking. It implies that the API changes are not breaking, when they are.

I think "Other changes" is better.

[GuySartorelli]

See #757 (comment) in response to "breaking changes" vs "other changes"

Seems like the PR is mostly about just reordering existing content without changing much of it.

Yes, I figured restructuring should be its own PR, and updating content should be separate, or else it would be a nightmare to review.

I feel the changelog in this PR reads somewhat negatively, because at the top it has several "things that are going away" e.g. modules loosing commercial support.
I think the changelog should lead with "new features" which is what people will be most looking forward to seeing. As much as we go on about "majors are for breaking changes", people are always asking about "what new features are in CMS 6", so we may as well arrange things to meet other peoples expectations.

I would prefer to keep the changes to supported modules at the top, because:

1. that will be directly below the "modules included in this release" which keeps things logically grouped
2. that and the other dependency changes are the sort of thing developers should ideally look at the earliest point of scoping an upgrade. "What's changed in my dependencies, and what additional things outside of my own code do I need to worry about?"

I don't think people scoping and performing upgrades from CMS 5 to CMS 6 will care that much about new features - they are likely to want to perform a like-for-like upgrade which means they need to know about breaking changes and information pertinent to their upgrade primarily.

I also don't think there's anything "negative" about the ordering of the changelog. It's known that a major release includes breaking changes. Besides which, the changelog isn't a marketing tool, it's an upgrade tool. IMO the order should be whatever's most helpful to people using the changelog to upgrade their projects, but within a logical structure (e.g. don't put features and enhancements last because the API stuff should ideally come just before the full list of API changes, which groups nicely with the commits list).

Note that within "Change to commercially supported modules" I've reoorded things so that the "new" stuff is up the top and the "going away" stuff is down the bottom

Similarly to my thoughts about the order as a whole - I think the order here should be "what is most useful for upgrades" which ideally puts the changes to existing support first.

[emteknetnz]

OK I guess if we assume the target audience is developers scoping a CMS 6 upgrade then that order makes sense

[GuySartorelli]

Yeah I think we have to assume that - the blog post is for a less technical audience, but the changelog kinda has to be for developers or else we will have to start having discussions like "is that too technical a detail? Will non-technical people understand this?" which starts to diminish the usefulness of the changelog.

[GuySartorelli]

I've rearranged stuff within the now-combined features and enhancements section in a way that I think makes sense - with things more likely to affect upgrades higher in the list, and things less likely to affect upgrades lower in the list (but also with things that are thematically similar close to each other).

[GuySartorelli]

I have now also:

1. Added missing links to the following sections:
   • "Support for PHPUnit 11"
   • "getCMSValidator method no longer supported"
2. Moved "New SingleRecordAdmin class and changes to SiteConfig" out of the "Changes to LeftAndMain and its subclasses" section and into "Features and enhancements" (felt like it deserved its own section, and that seems like the best place for it)
3. Moved "Most extension hook methods are now protected" up to be next to "Changes to some extension hook names" since they're thematically linked
4. Added links between the "FormField classes now use FieldValidator for validation" and "validation added to DBFields" sections - anyone dealing with validation in the CMS should be aware that these are connected - though their positions in the list I think are appropriate as one is a new feature while the other is kinda an API change for an existing feature. Happy to move "FormField classes now use FieldValidator for validation" into features and enhancements though if you prefer.