Structure breaking changes so users can quickly decide if they apply to them

romaricpascal commented 8 months ago

What

Help readers quickly identify:

if a breaking change applies to them
what they need to look for to know
what they need to change in their code
what they need to look for to know the update went OK

With the deprecations that are now removed, it could be helpful to provide more explicit examples of what to remove (classes, mixins, deprecation warnings) for each of them, maybe links to previous releases where the bit was deprecated.

Why

This should help users decide what they need to update or not, assess the impact of the update and make it happen.

Who needs to work on this

Developers, Tech writers

Who needs to review this

Developers, Tech writers

Done when

[ ] Breaking changes have been restructured to pick up these pieces of information easily

romaricpascal commented 7 months ago

Also ensure headings consistently refer to actions the users need to take.

This issue will probably be best handled by pairing for a couple of hours.

romaricpascal commented 7 months ago

Updated in the draft changelog (internal).

If anyone notices a way a specific section could be better structured, feel free to suggest updates on the draft though.

alphagov / govuk-frontend-docs