From 9fd9ef2df868f97ab43161234951b56581700074 Mon Sep 17 00:00:00 2001
From: Peter Lebbing <peter@digitalbrains.com>
Date: Wed, 13 Apr 2022 16:46:01 +0200
Subject: [PATCH] Document changelog best practices

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:

```bash
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.
---
 changelog/README.md | 37 +++++++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/changelog/README.md b/changelog/README.md
index 07016bcb45..0b2d3dd877 100644
--- a/changelog/README.md
+++ b/changelog/README.md
@@ -6,6 +6,39 @@ somewhat manageable:
 * Create a changelog file: `touch $(date --iso-8601=seconds | tr : _)_my_change_message`
 * We collect these files for each release and put their messages in
   `CHANGELOG.md`. The files are subsequently deleted.
-* Messages should be valid Markdown
 
-I've added an example to the commit introducing this change.
+A changelog file can contain multiple entries. Each entry starts with a tag
+word from the list below, followed by one or more lines of text in Markdown
+format. An entry should mention the GitHub PR that introduces the change or the
+GitHub issue that the change fixes.
+
+Changelog entries should be understandable as a stand-alone text; it should give
+the reader an overview of the change without needing to consult more
+documentation, but it can refer to other documentation for further information.
+A Changelog entry is allowed to be verbose, but it need not duplicate
+documentation; a link to further documentation is often enough.
+
+Example:
+
+```
+ADDED: Commodo eros. Suspendisse tincidunt mi vel metus. [#1234](https://github.com/clash-lang/clash-compiler/pull/1234)
+FIXED: Facilisis neque. Nulla mattis odio vitae tortor. [#1234](https://github.com/clash-lang/clash-compiler/issues/1234)
+```
+
+The tags we use are:
+ * ADDED:
+ * FIXED:
+ * CHANGED:
+ * DEPRECATED:
+ * REMOVED:
+ * INTERNAL NEW:
+ * INTERNAL FIX:
+ * INTERNAL CHANGE:
+ * DOCUMENTATION:
+   (meaning something that only affects documentation, not code)
+
+Usually, the name of the section in the CHANGELOG is equal to the tag;
+the exceptions are:
+ * INTERNAL NEW: Listed in a CHANGELOG section named _New internal features:_
+ * INTERNAL FIX: Listed in a CHANGELOG section named _Internal fixes:_
+ * INTERNAL CHANGE: Listed in a CHANGELOG section named _Internal changes:_