[RFC] Improved changelog format

[straight-shoota]

I think the changelog format could be restructured to be more useful for readers.

The current format (example for 1.8.0) is structured by topic: Language changes at the top, then stdlib changes, then compiler, tools and infrastructure. Internally, these section can be further divided into subsections. Topics correspond to the topic:* labels in GitHub.

While this is a somewhat useful structure, it does little to communicate to the users what impact a change has for them. There are some hints on that, for example the conventional verb at the beginning of the change description ("Add", "Fix", "Refactor"), or the indicator for breaking changes.
But readers need to skim the entire changelog to find potentially relevant information. It would be much better to put the most important stuff on top to make it easily accessible.

So I'm proposing to refactor the changelog format.

• The first order of hierarchy is the type of change. This corresponds to the kind:* labels in GitHub, which are currently not considered in the changelog.
  Each type corresponds to a section which would be sorted by relevance like this:
  • Features
  • Bugfixes
  • Performance
  • Refactor
  • Documentation
  • Specs
  • Infrastructure
• The second level is the main topic. This is equivalent to the first hierarchy in the current changelog, which is essentially pushed down one level. The order stays identical:
  • Language
  • Standard library
  • Compiler
  • Tools
  • Other
• Finally there is the list of changelog entries, no further subsections. Instead, each entry is prefixed by the subtopic (for example codegen or networking). This communicates which part of the code base it affects. Entries are sorted by subtopic (to group related changes) and merge date.

I have created an example in this format for the 1.9.0 changelog in https://github.com/straight-shoota/crystal/tree/feature/changelog-1.9.0-new.
Check out the preview.

There's no rush to roll this out for 1.9, but we can if the proposal is accepted in time.

[Sija]

I'd group breaking changes together to avoid a need to go through the whole changelog just to learn about those.

[straight-shoota]

I was wondering about that as well.
Breaking changes should probably have the highest priority, above feature additions.

But what we're usually annotating as "breaking" in minor releases are only soft breaking changes, typically API deprecations. They won't actually break anything directly. So it's less relevant to learn about them right away. Compiler warnings will tell you about them if you use them.
Maybe we should use a different annotation for that (label:deprecation?) to make a difference between adding a deprecation notice and actuall hard breaking changes.

[Sija]

Yeah, I believe that warrants another label as they're two distinct situations.

[beta-ziliani]

Many of the breaking changes listed there are actual breaking changes and not deprecations anyway (just not super relevant, but still).

EDIT: I think it makes sense to add a Breaking change section.

[straight-shoota]

I added a section for breaking changes. For that I have created the label kind:breaking.
Additionally, I created the label deprecation for designating deprecations.
I figure those two could together replace the previous breaking-change label. Alternatively, we could keep that label instead of kind:breaking but IMO it makes a lot of sense for labels that correspond to a changelog section have the kind: prefix.

Preview

[beta-ziliani]

Sounds good. Can't a label be renamed? Because that would be best, in order to avoid having duplicated labels.

[straight-shoota]

Yes, renaming is possible. But so far the breaking-change label had a broader scope than kind:breaking. That's why I refrained from just renaming it directly.

[Sija]

Now we have Breaking changes section I'm thinking that having a one for Deprecations would be helpful too.

[straight-shoota]

I don't think they are relevant enough for that. A deprecation isn't really a substantial change on its own.
It attaches a heads-up warning about a feature being removed in a future release. That's essentially adding machine-readable documentation.

[Sija]

Deprecation is an important indicator IMO warranting a section of its own. These will become removed in future versions, so you'd like to have a clear list of 'em before that happens.

[straight-shoota]

Definitely! But I don't think the changelog is the right place for that.
Breaking changes are specifically highlighted because they may require immediate attention. Deprecations do not. They are not urgent and thus less important.
We should still point them out clearly, of course. But I think the release notes are a better place for that. Maybe we could also introduce a dedicated UPDATING.md file to keep track of disruptive changes and instructions for dealing with them.

For practical reasons, deprecations are often merely by-products of other changes. For example #13550 is a feature addition which in the process of adding a new method signature, deprecates the old one. It makes a lot of sense to have all this in a single code change. On a higher level, it's two different changes for Dir.glob: "Add overloads with match parameter" and "Deprecate overloads with match_hidden parameter". But that's way too much detail for the changelog (there are lots of other small changes in this PR!).

[beta-ziliani]

+1 to having an UPDATING.md file, and +1 that release notes are a better place to read about such stuff.