chore(changelog): use 'keep a changelog' format

[kchibisov]

Links: https://keepachangelog.com/en/1.0.0/

--

I was thinking maybe we can try to link the changed APIs, since it should be possible now?

I'm also not really liking the way the platform changes look. Maybe use a subsection for them? And for toplevel changes write with a implemented on X, Y, and Z?

[notgull]

Looks good to me!

[daxpedda]

These have become pretty hard to read.

I do agree that now that we have headers for each change type, we shouldn't use the word "add" or "removed" in every entry, but it should still remain readable.

The main issue imo is starting sentences with "On Windows, ...", but then missing the verb, its really odd to read.

My suggestion would be to change the whole "On Windows, ..." to "Windows: ".
Not a native speaker though, @notgull any thoughts?

[kchibisov]

My suggestion would be to change the whole "On Windows, ..." to "Windows: ".
Not a native speaker though, @notgull any thoughts?

Yeah, I don't like it as well as I said.

[notgull]

I agree with adding the indicator before the actual addition.

[kchibisov]

The alternative could be putting in the end of the sentence, which also makes it correct, or create sub sections, which is more clean.

[daxpedda]

I'm in favor of sub sections.

[notgull]

I'm fine with whichever option other maintainers prefer.

[madsmtm]

From a user perspective, I think it's more interesting to see (in order, and roughly in the groups that I think are relevant):

• Large changes or reworks.
• Minor additions, changes, removals or deprecations.
• Changed platform-specific behaviour, with one section per platform.

Re grammar: For projects that use Keep A Changelog, I appreciate when they still add the header name (or something more descriptive) to each entry (e.g. - Added services menu over - Services menu). Changelogs are for humans, they don't have to be the absolute minimal they can be.

But don't have that strong of a preference here.

[daxpedda]

LGTM!

I agree with @madsmtm that this is for humans and therefor should be "human-friendly" and not minimal.
Lets wait for our meeting before merging.

[kchibisov]

I've added a separate commit as alternative way to structure changelog.

[daxpedda]

Now that we have sentences I think a dot at the end would be appropriate.

I missed the last meeting, did you decide to remove subsections or what happened here?

[kchibisov]

@madsmtm suggested that we should write more correct sentences and subsections ones were harder to read, especially if you want to do inline migrations next to relevant change.

go ahead with fixing formatting as you like.

[madsmtm]

Fine with this now.