Changelog creation: further improvements

[talldan]

Todos

• Use subheadings (####) instead of list items (-) for subheading categories. This keeps all lists at a single level which is easier for maintenance and authoring. Automated changelog - use nested headings for feature groups instead of indenting lists #34040
• Group all documentation tasks under one 'Documentation' main heading, instead of trying to subcategorize them. We had some under Tools that could/should be under the main Documentation heading. Auto changelog - force group all docs tasks under Documentation #34042
• Adjust ordering according to Changelog creation: further improvements #33719 (comment)
• Rename 'Editor' to 'Post Editor' to avoid ambiguity with other editors.
• Remove Uncategorized feature group heading and allow items to exist at top level Automated changelog: remove Uncategorized header in output and place items at top #34037

[getdave]

Thanks so much for the feedback @talldan 🙌

Can I clarify that you understand that the automation only provides a draft of the changelog. Typically then the release lead reorganises it as they see fit. Therefore the current RC may be more reflective of the release lead's changes rather than the changelog automation.

If you'd like to see what the automation generates for 11.2.0 then you can run:

npm run changelog -- --milestone="Gutenberg 11.2" --token=YOUR_GITHUB_PERSONAL_ACCESS_TOKEN

Use subheadings (####) instead of list items (-) for subheading categories

That's just the format folks have been using for the past few releases. If @priethor and co are happy to adjust to subheadings then it's trivial to update the code.

Group all documentation tasks under one 'Documentation' main heading, instead of trying to subcategorize them

This makes sense although I would have hoped the automation would do that already. It did on my test run.

Adjust ordering

Could you elaborate a little here?

Rename 'Editor' to 'Post Editor' to avoid ambiguity with other editors

Seems logical although we might need to add labels for the various editors in order that the automation can distinguish between them.

[talldan]

I realise there's not much detail in my notes, just things that I jotted down as I was doing the release

Can I clarify that you understand that the automation only provides a draft of the changelog. Typically then the release lead reorganises it as they see fit. Therefore the current RC may be more reflective of the release lead's changes rather than the changelog automation.

Yep, I was the release lead and organised the changelog.

That's just the format folks have been using for the past few releases. If @priethor and co are happy to adjust to subheadings then it's trivial to update the code.

It does make it a bit easier to re-organise things when all the bullet points are at the same level, and I think it might look tidier.

This makes sense although I would have hoped the automation would do that already. It did on my test run.

There's one that's like this, so you may have missed it. There's a documentation sub-heading under 'Tools' for this PR - #33473. I also adjusted the labels on some other PRs, so how it generates now might not be reflective.

Could you elaborate a little here?

Under Enhancements, the top two things were 'Components' and 'Accessibility', which are areas that I don't think generally contain the most noteworthy features. I think it'd be better to show block library, and editor enhancements above those.

Also, widgets editor changes were above block/post editor changes.

Seems logical although we might need to add labels for the various editors in order that the automation can distinguish between them.

I think it's fine to say that anything from the Editor package is shown as 'Post Editor'. The site editor is the only other editor that uses the editor package, but PRs will have the Site Editor label, which should take precedence. So I think we can make anything with [Package] Editor appear in the changelog as 'Post Editor' for greater clarity. Otherwise Editor is a little ambiguous alongside Block Editor, Widgets Editor, Site Editor etc.

[getdave]

Nice - thanks for all that feedback. It's pretty clear and I think it should be actionable.

[gziolo]

Should we close #30538 that is more higher-level and already got some improvements? We just should consolidate all issues related to the changelog and create a detailed todo list to make it all simpler to discuss further steps.

There are also other related issues:

• Build tooling: update release docs with information on automated grouping by feature request #33568 and PR proposed Update docs to reflect new automated process for feature grouping #33573
• Release changelog tooling: add a subgroup for the block library and detect the block name #33565

[priethor]

That's just the format folks have been using for the past few releases. If @priethor and co are happy to adjust to subheadings then it's trivial to update the code.

I don't feel strongly about a change of formatting, we can see how it looks and decide. However:

It does make it a bit easier to re-organise things when all the bullet points are at the same level, and I think it might look tidier.

I can't agree more with this 😅. Having items at different indentation levels makes it harder to reorganize things and to export the changelog to a spreadsheet.

[priethor]

I think it's fine to say that anything from the Editor package is shown as 'Post Editor'. The site editor is the only other editor that uses the editor package, but PRs will have the Site Editor label, which should take precedence.

I think we should avoid assuming all these PRs belong to the Post Editor. Apart from the Site Editor there is the Template Editor, even though it's accessed through the Post Editor, and there might soon be isolated template part editors.

[priethor]

Group all documentation tasks under one 'Documentation' main heading, instead of trying to subcategorize them. We had some under Tools that could/should be under the main Documentation heading.

What would be the downside of sub categorizing documentation? For example, Gutenberg 11.1 had a lot of documentation updates, and grouping them in (at least) one level can help differentiate between package documentation and handbook updates.

As far as I have seen, the issue with having documentation PRs classified in other main categories is usually related to the label categorization priority. In my opinion, any PR containing a Documentation label should go under Documentation, regardless of the nature of the item being documented.

[talldan]

I think we should avoid assuming all these PRs belong to the Post Editor. Apart from the Site Editor there is the Template Editor, even though it's accessed through the Post Editor, and there might soon be isolated template editors.

True, maybe we need a specific 'Post Editor' label to be able to differentiate changes that only apply to the post editor.

I can't agree more with this 😅. Having items at different indentation levels makes it harder to reorganize things and to export the changelog to a spreadsheet.

Cool, I'll look into this.

What would be the downside of sub categorizing documentation?

I think subgroupings within documentation are good. I only just realised my initial comment probably wasn't very clear. Some documentation items were outside the main documentation category (tools > documentation), instead I think we should keep them all under the main one (documentation > tools). Sounds like there's agreement on this, so it seems like a small bug to fix.

[gziolo]

It looks like there is only one task left:

Rename 'Editor' to 'Post Editor' to avoid ambiguity with other editors.

[priethor]

Rename 'Editor' to 'Post Editor'

Would Editor include Block Editor as well? I've seen both namings and unless I'm missing something, they both refer to "any editor that is not specifically the site or template one", don't they?.

On the other hand, aren't there use cases where changes only affect the post editor but not other block editors?

[priethor]

Just answering myself here: the Editor package depends on the Block Editor one and is effectively the Post Editor. Thanks to both packages' documentation for clarifying that despite the misleading Editorname! 👍

[gziolo]

Just answering myself here: the Editor package depends on the Block Editor one and is effectively the Post Editor. Thanks to both packages' documentation for clarifying that despite the misleading Editorname! 👍

Yes, it has always been confusing. I added some more clarifications earlier this year in #30136 because I had trouble reasoning what's the purpose of @wordpress/editor in the world with the widgets editor or the navigation editor 😅

[gziolo]

There is one more task, we should revisit if we still want to have it (#33565):

add a subgroup for the block library and detect the block name

[priethor]

I've seen a great improvement in the raw changelog when curating the 11.3 one. As not all improvements were in place yet, I'll wait until 11.4 to see what areas would benefit the most from further improvements. Thanks all for the effort in improving this process 💯

[getsource]

First, thanks for everyone's work on this! It's pretty amazing to have such an excellent automated starting point for the changelog.

A few notes so far from what I found while going through -- if some of these are intentional, apologies.

• Many 'Code Quality' items were not grouped by their package label.
• Things with 'Core Data' package label were commonly not put into a heading/category.
• 'Block Editor' package labeled items seemed not to have a heading/category in 'Bugs'.

[getdave]

@getsource Glad it was useful ✨

It would be great if you could consider opening a new Issue(s) to track these concerns.

Happy to address them in due course.

Thanks again for leading the release. Great job there 🚀

[getsource]

Thanks much for the kind words!

Sure, thanks! I'll think about the best way to turn the observations into actionable issue(s).