From 113970566bad18c3de41ff7b2dcf004ed5c0bfec Mon Sep 17 00:00:00 2001
From: Dorota Czaplejewicz <dorota.czaplejewicz@puri.sm>
Date: Sat, 3 Sep 2022 12:17:02 +0000
Subject: [PATCH] docs: Add NEWS.md

---
 doc/hacking.md     | 36 ++++++++++++++++++++++++++----------
 tools/make_message | 36 ++++++++++++++++++++++++++++++++++++
 2 files changed, 62 insertions(+), 10 deletions(-)
 create mode 100755 tools/make_message

diff --git a/doc/hacking.md b/doc/hacking.md
index 0cc54d22..33bce18a 100644
--- a/doc/hacking.md
+++ b/doc/hacking.md
@@ -254,16 +254,32 @@ Inspect `debian/changelog`, and make sure the first line contains the correct ve
 squeekboard (1.13.0pureos0~amber0) amber-phone; urgency=medium
 ```
 
-Commit the updated `debian/changelog`. The commit message should contain the release version and a description of changes.
+Add the updated `debian/changelog` to the commit. The commit message should contain the release version and a description of changes.
 
-> Release 1.13.0 "Externality"
->
-> Changes:
->
-> - A system for latching and locking views
-> ...
+### 5. Update the NEWS file
 
-### 5. Create a signed tag for downstreams
+Summarize the changes since the last release in the NEWS file. Use the Markdown syntax, e.g.
+
+```
+1.13.0 "Externality"
+-----------------------------
+
+Changes:
+- A system for latching and locking views
+...
+```
+
+### 6. Commit changes
+
+Generate a commit message from the news file:
+
+```
+tools/make_message | git commit --file=- ...
+```
+
+If the commit message looks wrong, fix the NEWS file, and do `git commit --amend`.
+
+### 7. Create a signed tag for downstreams
 
 The tag should be the version number with "v" in front of it. The tag message should be "squeekboard" and the tag name. Push it to the upstream repository:
 
@@ -272,7 +288,7 @@ git tag -s -u my_address@example.com v1.13.0 -m "squeekboard v1.13.0"
 git push v1.13.0
 ```
 
-### 5. Create a signed tag for packaging
+### 8. Create a signed tag for packaging
 
 Similar to the above, but format it for the PureOS downstream.
 
@@ -281,6 +297,6 @@ git tag -s -u my_address@example.com 'pureos/1.13.0pureos0_amber0' -m 'squeekboa
 git push 'pureos/1.13.0pureos0_amber0'
 ```
 
-### 6. Rejoice
+### 9. Rejoice
 
 You released a new version of Squeekboard, and made it available on PureOS. Congratulations.
diff --git a/tools/make_message b/tools/make_message
new file mode 100755
index 00000000..07936b8f
--- /dev/null
+++ b/tools/make_message
@@ -0,0 +1,36 @@
+#!/usr/bin/env python3
+
+"""Extracts commit message for the last release from NEWS.md file.
+"""
+
+from itertools import dropwhile
+import sys
+
+with open('NEWS.md') as f:
+    contents = f.readlines()
+
+    if contents[0].startswith('## '):
+        name = contents[0][3:]
+        contents = contents[1:]
+    elif contents[1].startswith('---'):
+        name = contents[0]
+        contents = contents[2:]
+    else:
+        raise ValueError("Can't find release name")
+    name = name.strip()
+
+print("Release", name)
+# git wants a single newline between commit title and message body
+print()
+# meanwhile, markdown ignores newlines after a title
+contents = dropwhile(lambda x: x.strip() == '', contents)
+
+# Need to look up forward
+contents = list(contents)
+
+for line, nextline in zip(contents, contents[1:] + ['']):
+    if nextline.startswith('---') or line.startswith('## '):
+        break
+    elif nextline.startswith('===') or line.startswith('# '):
+        raise ValueError("Encountered title instead of release section")
+    print(line.strip())