Document changelog best practices

[DigitalBrains1]

This is a discussion piece to improve our developer documentation on writing
entries for the CHANGELOG. Please propose any changes you'd like.

Since we want to automate changelog file processing in the future, the
tags should be rigidly defined. But even without automation, it's
helpful if they are.

I extracted a partial list of tags used in changelog files in the
master branch so far with the oneliner:

git log --oneline -p --no-show-signature master -- :/:changelog | grep -A1 '^@@ -0,0'|grep '^+'|sed 's/^.\([^:]\+\).*/\1/'|sort|uniq -c|sort -nr

It will approximately show what the first line of a newly created file
in the changelog/ directory says up to its first colon, grouped by
occurence frequency. It produced the following result:

     80 FIXED
     52 CHANGED
     24 ADDED
      6 FEATURE
      5 INTERNAL CHANGE
      5 FIXES
      4 Fixed
      3 DEPRECATED
      2 #!/usr/bin/env python3
      2 REMOVED
      2 * New features (API)
      2 Inspired by [Solving Gitlab's CHANGELOG crisis](https
      2 CHANGED (internal)
      1 NEW
      1 FIX
      1 # clash-lib
      1 CHANGED,FIXED
      1 CHANGED / FIXED
      1 CHANGE
      1 Add support for Yosys compatible SVA to `Clash.Verification`. This enables

From this list, I picked FIXED, CHANGED, ADDED, INTERNAL CHANGE,
DEPRECATED, and REMOVED.

I also looked at /CHANGELOG.md to see what other categories are useful,
and invented the remaining tags for that:

INTERNAL NEW, INTERNAL FIX and DOCUMENTATION.

Still TODO:

• Write a changelog entry (see changelog/README.md) 😋
• Check copyright notices are up to date in edited files

[alex-mckenna]

+1 for trying to make documentation more consistent.

From this list, I picked FIXED, CHANGED, ADDED, INTERNAL CHANGE, DEPRECATED, and REMOVED.
I also looked at /CHANGELOG.md to see what other categories are useful, and invented the remaining tags for that:

INTERNAL NEW, INTERNAL FIX and DOCUMENTATION.

To bikeshed: I would consider deprecation to be a change instead of some special thing. I also wonder if there's any benefit to distinguishing between additions / changes / fixes when the change is purely internal. Internal changes don't matter as much to people reading the changelog IMO. This would also make it more consistent with DOCUMENTATION, which can also be added or changed, but you don't distinguish between the two cases.

Why do you suggest adding NEW? Isn't that covered by ADDED?

I suspect @martijnbastiaan will have some thoughts vis-à-vis making sure changelogs are consumable by any tooling we may want later (like automatically updating the changelog for a tag, which I think he was talking about the other week).

[alex-mckenna]

Ah, you had already requested a review from Martijn, I didn't see before 🙃

[DigitalBrains1]

Why do you suggest adding NEW? Isn't that covered by ADDED?

All but DOCUMENTATION and INTERNAL are past participles, but that makes no grammatical sense following the word INTERNAL, as exemplified by the existing difference between CHANGED and INTERNAL CHANGE. INTERNAL ADDITION was just a bit of a mouthful, so I picked INTERNAL NEW.

[martijnbastiaan]

From this list, I picked FIXED, CHANGED, ADDED, INTERNAL CHANGE,
DEPRECATED, and REMOVED.

That seems sensible.

[martijnbastiaan]

I tend to rewrite these quite often because the changelogs included are often along these lines:

Don't render extended identifiers in SDC files

This is fine for commit messages, but for the changelog I'd like to see:

Clash no longer escapes extended identifiers when rendering SDC files, this improves blabla

So I think it would be nice to replace the lorum ipsum with some examples.

[martijnbastiaan]

✔️