Document 14.0.0 migration guide

[jeddy3]

Which issue, if any, is this issue related to?

Closes #5301

Is there anything in the PR that needs further explanation?

I figured I'd get the ball rolling on this to elicit feedback. We won't be able to merge this until the dust settles on custom syntaxes and shared configs, and we know what we can point to at release time.

The pull request touches quite a few markdown files. This was necessary to pull all the bits together.

Highlights of changes:

• added migrating details in the changelog
• revamped the getting started guide to match this
• options.md is the canonical place for details, with configure.md linking to it (like we already do with cli.md)
• reordered the properties inconfigure.md to make more sense (and emphasise the customSyntax and overrides properties)
• added an early draft of more helpful messages when:
  • using the syntax option
  • attempting to lint a non-CSS file without specifying a custom syntax

That last one is quick and dirty to check that this is the kind of thing we had in mind?

[jeddy3]

@hudochenkov Thanks for the suggestions. I've made those changes.

[jeddy3]

I simplified the error messaging. However, feel free to push to this pull request this week if anyone has ideas for improvements.

(Linting is failing on a missing Markdown link references, which can be ignored for now.)

[ybiquitous]

Perhaps, I think it may be better to create a migration document like docs/migration-guide/v13-to-v14.md, instead of updating CHANGELOG.md. 🤔
(CHANGELOG.md has frequently changed and will be bigger)

What do you think?

[jeddy3]

Perhaps, I think it may be better to create a migration document like docs/migration-guide/v13-to-v14.md, instead of updating CHANGELOG.md. 🤔
(CHANGELOG.md has frequently changed and will be bigger)

It's a good suggestion. I'll pull the migration guide out when I'm back next week.

[jeddy3]

I've pulled the content into a new migration guide section.

I've also pulled out all the shared-config stuff until it's ready so that we can merge this and I can work on #5564. We can add the shared-config stuff back (in follow-up pull request) when it lands.

This pull request is mainly about customSyntax now and changes to support that.

Pull request is ready for review.

[ybiquitous]

@jeddy3 Thank you for extracting the v14 migration guide as another file!

I've left some trivial suggestions and questions.

[jeddy3]

@ybiquitous Thanks for the suggestions. I'm always impressed by your keen eyes!

@hudochenkov I've added a couple of commits for your suggestions. I've also added to the discussion as the syntaxes that extract styles seem more compatible with PostCSS@8 than I originally thought.

[hudochenkov]

Fantastic work, @jeddy3!