Improve release instructions

Author: mpkorstanje

RELEASING.md

@@ -18,64 +18,51 @@ Also check if you can upgrade any dependencies:
 make update-dependency-versions
 ```
 
-## Make the release ##
+## Decide what the next version should be ##
+
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). To sum it up, it depends on what's changed (see `CHANGELOG.md`). Given a version number MAJOR.MINOR.PATCH:
 
-In order to make releases secrets are required. Members of the core
-team can install keybase and join the `cucumberbdd` team to access these secrets.
+* Bump `MAJOR` when you make incompatible API changes:
+  * There are `Removed` entries, or `Changed` entries breaking compatibility
+  * A cucumber library dependency upgrade was major
+* Bump `MINOR` when you add functionality in a backwards compatible manner:
+  * There are `Added` entries, `Changed` entries preserving compatibility, or
+  `Deprecated` entries
+* Bump `PATCH` when you make backwards compatible bug fixes:
+  * There are `Fixed` entries
 
-Remove the empty sections in the changelog. Don't commit these but run: 
+Display future version by running:
 
 ```
 make version
 ```
 
-Check if branch name and version are as expected.
+Check if branch name and version are as expected. To change version run:
 
 ```
-make release
-``` 
+mvn versions:set -DnewVersion=X.Y.Z-SNAPSHOT
+```
 
-# GPG Keys #
+## Secrets ##
 
-To make a release you must have the `[email protected]` GPG private key imported in gpg2.
+Secrets are required to make releases. Members of the core team can install
+keybase and join the `cucumberbdd` team to access these secrets.
 
-```
-gpg --import devs-cucumber.io.key
-```
+During the release process, secrets are fetched from keybase and used to sign
+and upload the maven artifacts.
 
-Additionally upload privileges to the Sonatype repositories are required. See the 
-[OSSRH Guide](http://central.sonatype.org/pages/ossrh-guide.html) for instructions. Then an 
-administrator will have to grant you access to the cucumber repository.
+## Make the release ##
 
-Finally both your OSSRH credentials and private key must be setup in your `~/.m2/settings.xml` - 
-for example:
+Check if branch name and version are as expected:
 
 ```
-<settings>
-    <servers>
-        <server>
-            <id>ossrh</id>
-            <username>sonatype-user-name</username>
-            <password>sonatype-password</password>
-        </server>
-    </servers>
-    <profiles>
-        <profile>
-            <id>ossrh</id>
-            <activation>
-                <activeByDefault>true</activeByDefault>
-            </activation>
-            <properties>
-                <gpg.executable>gpg2</gpg.executable>
-                <gpg.useagent>true</gpg.useagent>
-            </properties>
-        </profile>
-        <profile>
-            <id>sign-with-cucumber-key</id>
-            <properties>
-                <gpg.keyname>dev-cucumber.io-key-id</gpg.keyname>
-            </properties>
-        </profile>
-    </profiles>
-</settings>
+make version
+```
+
+Do the release:
+
 ```
+make release
+``` 
+
+All done! Hurray!

scripts/remove-empty-sections-changelog.awk

@@ -0,0 +1,30 @@
+function start_buffering() {
+  buf = $0
+}
+function store_line_in_buffer() {
+  buf = buf ORS $0
+}
+function clear_buffer() {
+  buf = ""
+}
+/^### (Added|Changed|Deprecated|Removed|Fixed)$/ {
+  start_buffering()
+  next
+}
+/^## / {
+  clear_buffer()
+}
+/^ *$/ {
+  if (buf != "") {
+    store_line_in_buffer()
+  } else {
+    print $0
+  }
+}
+!/^ *$/ {
+  if (buf != "") {
+    print buf
+    clear_buffer()
+  }
+  print $0
+}

scripts/update-changelog.sh

@@ -6,6 +6,7 @@ set -uf -o pipefail
 # * The [Unreleased] diff link is updated
 # * A new diff link for the new release is added
 # * The ## [Unreleased] header is changed to a version header with date
+# * The empty sections are removed
 # * A new, empty [Unreleased] paragraph is added at the top
 #
 
@@ -43,7 +44,7 @@ changelog=$(echo "${changelog}" | sed "s/## \[Unreleased\] (In Git)/## \[${new_v
 # Update [Unreleased] diff link
 line_number_colon_unreleased_link=$(echo "${changelog}" | grep -n "\[Unreleased\]")
 line_number=$(echo "${line_number_colon_unreleased_link}" | cut -d: -f1)
-unreleased_link=$(echo "${line_number_colon_unreleased_link}" | cut -d' ' -f2)
+unreleased_link=$(echo "${line_number_colon_unreleased_link}" | awk '{print $2}')
 
 if [[ "${unreleased_link}" =~ \/v([0-9]+\.[0-9]+\.[0-9]+(-RC[0-9]+)?) ]]; then
   last_version="${BASH_REMATCH[1]}"
@@ -59,12 +60,21 @@ insertion_line_number=$((line_number + 1))
 release_link=$(echo "${changelog}" | head -n ${insertion_line_number} | tail -1)
 new_release_link=$(echo "${release_link}" | \
   sed "s/${last_version}/${new_version}/g" | \
-  sed "s/v[0-9]\+.[0-9]\+.[0-9]\+/v${last_version}/")
+  sed -E "s/v[0-9]\+.[0-9]\+.[0-9]\+/v${last_version}/")
 
-changelog=$(echo "${changelog}" | sed "${insertion_line_number} i ${new_release_link}")
+changelog=$(echo "${changelog}" | sed "${insertion_line_number} i \\
+${new_release_link}
+")
+
+# Remove empty sections
+
+scripts_path="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+changelog=$(echo "${changelog}" | awk -f "${scripts_path}/remove-empty-sections-changelog.awk")
 
 # Insert a new [Unreleased] header
 
-changelog=$(echo "${changelog}" | sed "s/----/----\n${header_escaped}\n/g")
+changelog=$(echo "${changelog}" | sed "s/----/----\\
+${header_escaped}\\
+/g")
 
 echo "${changelog}"