Process update: call out breaking changes in "What’s new in Gutenberg?" posts and changelog

[simison]

Is your feature request related to a problem? Please describe.

Changelogs for @wordpress/* package updates are great in that they are following semantic versioning and contain the "breaking changes" section in the changelog (example). 🎉

Neither is true for Gutenberg plugin updates tho. 😞

For example in the latest update post and plugin changelog we had:

Various
Block Editor: Remove (more) legacy “editor-” class name compatibility

Describe the solution you'd like
A clear "breaking changes" section in the changelog would be helpful.

I don't mind if they're double, so the above example would be twice in the document. That way folks could only skim "breaking" section if they don't wanna read the whole thing.

Additional instructions on how to migrate would be helpful too.

"Upcoming breaking changes" could be another useful thing: so example of CSS class deprecation would be called out clearly upfront.

Describe alternatives you've considered
–

[simison]

Copying Slack convo over (https://wordpress.slack.com/archives/C02QB2JS7/p1579861260026000):

@gziolo
we usually apply Needs Dev Note to PRs that might introduce braking changes, we should do it always and mark that in the release post with a short note, that’s a good idea 👍

@youknowriad
We should avoid creating double work for us though, writing a dev note takes time. We need to create dev notes to cover these for WordPress and sometimes we do this for multiple related PRs at once. For instance I made at least 4 PRs related to the Button component in multiple plugin releases and I'd like to write a single dev note for it not one for each release.
Potentially we can just mark these items in the changelog somehow and leave it to the plugin user to check the details in the PR. Remember that Gutenberg is a development plugin.

@simison
We should avoid creating double work for us though, writing a dev note takes time.
Would there be a way to write them once, and then collect them up from each step to the next? So breaking notes in package changelogs end up in gutenberg plugin changelog and that ends up in WP core changelog?

@youknowriad
As I said above with the "button" example, that's not always possible when there's related work across releases.

@simison
Right, makes sense. I think looking up exact details in PRs is fair as long as those are somehow highlighted in release notes as potentially breaking.
Otherwise kinda every change becomes potentially breaking — know what I mean?

@youknowriad
Also, note that there's no big breaking changes in Gutenberg, it's very rare and the example you share above is not considered a breaking change

@youknowriad
Here's our exact policy https://developer.wordpress.org/block-editor/developers/backward-compatibility/

[simison]

The example I pointed out was actually highlighted at WP 5.2 changelog, as mentioned here: godaddy-wordpress/coblocks#1242 (comment)

[ellatrix]

I guess we should highlight any changes that already have the "Dev Note" label for the next WP release.

[mcsf]

We still collect all breaking changes manually, correct? Could we partly collect them by letting the release tool parse our packages' changelogs?

[gziolo]

We still collect all breaking changes manually, correct? Could we partly collect them by letting the release tool parse our packages' changelogs?

We include breaking changes mostly for tooling. I don't think that changelogs for UI related packages are often updated. It would be great to do that, but in practice, there is no data to process 😄

[mcsf]

but in practice, there is no data to process

Quite true, unless we could raise potential breakage in the course of feature work (PRs).

[sirreal]

I'd love it if these posts featured the Gutenberg version in the title. They seem to be release announcements but the Gutenberg version number is not mentioned in the title.

[youknowriad]

@sirreal Seems like a simple change we can do. If we forget on the next one, ping us :)

[inaikem]

+1 for the Gutenberg version in the title. It'll be a big help for me as I start pulling Gutenberg releases for distribution internally.

[simison]

Old issue, old convo; I think this served already for the change back then. :-)