chore(release): include deprecations in changelog (hawkw#235)

* chore(release): include "Deprecated" in changelog
* chore: factor out changelog updating script
* chore: add a header to the changelog

.shellcheckrc

@@ -0,0 +1 @@
+external-sources=true

bin/_util.sh

@@ -0,0 +1,80 @@
+#!/usr/bin/env bash
+# utility functions used in other shell scripts.
+#
+# currently, this includes:
+# - cargo-style stderr logging (`err`, `note`, and `status` functions)
+# - confirmation prompts (`confirm` function)
+set -euo pipefail
+
+# Log an error to stderr
+#
+# Args:
+#     $1: message to log
+err() {
+    echo -e "\e[31m\e[1merror:\e[0m" "$@" 1>&2;
+}
+
+# Log a note to stderr
+#
+# Args:
+#     $1: message to log
+note() {
+    echo -e "\e[31m\e[1mnote:\e[0m" "$@" 1>&2;
+}
+
+# Log a cargo-style status message to stderr
+#
+# Args:
+#     $1: a "tag" for the log message (should be 12 characters or less in
+#     length)
+#    $2: message to log
+status() {
+    local width=12
+    local tag="$1"
+    local msg="$2"
+    printf "\e[32m\e[1m%${width}s\e[0m %s\n" "$tag" "$msg"
+}
+
+# Prompt the user to confirm an action
+#
+# Args:
+#    $1: message to display to the user along with the `[y/N]` prompt
+#
+# Returns:
+#    0 if the user confirmed, 1 otherwise
+confirm() {
+    while read -r -p "$1 [Y/n] " input
+    do
+        case "$input" in
+            [yY][eE][sS]|[yY])
+                return 0
+                ;;
+            [nN][oO]|[nN])
+                return 1
+                ;;
+            *)
+                err "invalid input $input"
+                ;;
+        esac
+    done
+}
+
+# Returns the path to a Mycelium crate.
+#
+# Args:
+#     $1: crate name
+#
+# Returns:
+#     0 if the crate exists, 0 if it does not exist.
+crate_path() {
+    local crate="$1"
+    local mycoprefix='mycelium-';
+    if [[ -d $crate ]]; then
+        echo "$crate"
+    elif [[ -d "${crate#"$mycoprefix"}" ]]; then
+        echo "${crate#"$mycoprefix"}"
+    else
+        err "unknown crate $crate"
+        return 1;
+    fi
+}

bin/release

@@ -11,37 +11,13 @@ FLAGS:
 
 set -euo pipefail
 
-cd "$(dirname "$0")"/..
+bindir=$( cd "${BASH_SOURCE[0]%/*}" && pwd )
+rootdir=$( cd "$bindir"/.. && pwd )
 
-err() {
-    echo -e "\e[31m\e[1merror:\e[0m" "$@" 1>&2;
-}
-
-note() {
-    echo -e "\e[31m\e[1mnote:\e[0m" "$@" 1>&2;
-}
-
-status() {
-    local width=12
-    printf "\e[32m\e[1m%${width}s\e[0m %s\n" "$1" "$2"
-}
+# shellcheck source=_util.sh
+. "$bindir"/_util.sh
 
-confirm() {
-    while read -r -p "$1 [Y/n] " input
-    do
-        case "$input" in
-            [yY][eE][sS]|[yY])
-                return 0
-                ;;
-            [nN][oO]|[nN])
-                return 1
-                ;;
-            *)
-                err "invalid input $input"
-                ;;
-        esac
-    done
-}
+cd "$rootdir"
 
 verify() {
     status "Verifying" "if $crate v$version can be released"
@@ -99,34 +75,6 @@ update_version() {
     fi
 }
 
-update_changelog() {
-    if ! [[ -x "$(command -v git-cliff)" ]]; then
-        err "missing git-cliff executable"
-        if confirm "       install it?"; then
-            cargo install git-cliff
-        else
-            echo "okay, exiting"
-            exit 0
-        fi
-    fi
-
-    status "Updating" "changelog for $crate $version"
-
-    local git_cliff=(
-        git-cliff
-        --include-path "${path}/**"
-        --output "$changelog"
-        --config cliff.toml
-        --tag "$tag"
-    )
-
-    if [[ "$verbose" ]]; then
-        git_cliff+=("$verbose")
-    fi
-
-    "${git_cliff[@]}"
-}
-
 publish() {
     status "Publishing" "$crate v$version"
     cd "$path"
@@ -154,6 +102,18 @@ publish() {
     fi
 }
 
+update_changelog() {
+    # shellcheck source=update-changelog
+    . "$bindir"/update-changelog
+    changelog_status="$?"
+
+    if ! "$changelog_status"; then
+        err "failed to update changelog"
+        exit "$changelog_status"
+    fi
+}
+
+
 verbose=''
 dry_run=''
 
@@ -210,16 +170,7 @@ if [[ "${errexit+errexit}" ]]; then
     exit 1
 fi
 
-mycoprefix='mycelium-';
-if [[ -d $crate ]]; then
-    path="$crate"
-elif [[ -d "${crate#"$mycoprefix"}" ]]; then
-    path="${crate#"$mycoprefix"}"
-else
-    err "unknown crate $crate"
-    echo "$usage"
-    exit 1
-fi
+path=$(crate_path "$crate")
 
 cargo_toml="${path}/Cargo.toml"
 changelog="${path}/CHANGELOG.md"

bin/update-changelog

@@ -0,0 +1,92 @@
+#!/usr/bin/env bash
+usage="Updates the changelog for a Mycelium crate.
+
+USAGE:
+    $(basename "$0") [FLAGS] <CRATE_PATH> <TAG>
+
+FLAGS:
+    -h, --help      Show this help text and exit.
+    -v, --verbose   Enable verbose output."
+
+set -euo pipefail
+
+bindir=$( cd "${BASH_SOURCE[0]%/*}" && pwd )
+rootdir=$( cd "$bindir"/.. && pwd )
+
+# shellcheck source=_util.sh
+. "$bindir"/_util.sh
+
+cd "$rootdir"
+
+verbose=''
+
+for arg in "$@"
+do
+    case "$arg" in
+    -h|--help)
+        echo "$usage"
+        exit 0
+        ;;
+    -v|--verbose)
+        verbose="--verbose"
+        ;;
+    -*)
+        err "unknown flag $arg"
+        echo "$usage"
+        exit 1
+        ;;
+    *) # crate or version
+        if [[ -z "${path+path}" ]]; then
+            path="$arg"
+        elif [[ -z "${tag+tag}" ]]; then
+            tag="$arg"
+        else
+            err "unknown positional argument \"$arg\""
+            echo "$usage"
+            exit 1
+        fi
+        ;;
+    esac
+done
+
+if [[ -z "${path+path}" ]]; then
+    err "no version specified!"
+    errexit=1
+fi
+
+if [[ -z "${tag+tag}" ]]; then
+    err "no tag specified!"
+    errexit=1
+fi
+
+if [[ "${errexit+errexit}" ]]; then
+    echo "$usage"
+    exit 1
+fi
+
+if ! [[ -x "$(command -v git-cliff)" ]]; then
+    err "missing git-cliff executable"
+    if confirm "       install it?"; then
+        cargo install git-cliff
+    else
+        echo "okay, exiting"
+        exit 0
+    fi
+fi
+
+changelog_path="${path}/CHANGELOG.md"
+
+status "Updating" "$changelog_path for tag $tag"
+
+git_cliff=(
+    git-cliff
+    --include-path "${path}/**"
+    --output "$changelog_path"
+    --config cliff.toml
+    --tag "$tag"
+)
+if [[ "$verbose" ]]; then
+    git_cliff+=("$verbose")
+fi
+
+"${git_cliff[@]}"

cliff.toml

@@ -1,11 +1,19 @@
+# configuration file for git-cliff (0.7.0)
+
 [changelog]
+# changelog header
+header = """
+# Changelog\n
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n
+"""
 # template for the changelog body
 # https://tera.netlify.app/docs/#introduction
 body = """
 {% if version %}\
     ## {{ version | trim_start_matches(pat="v") }} - ({{ timestamp | date(format="%Y-%m-%d") }})
 {% else %}\
-    ## [unreleased]
+    ## Unreleased
 {% endif %}\
 {% if previous %}\
     {% if previous.commit_id %}
@@ -49,13 +57,14 @@ footer = """
 [git]
 conventional_commits = true
 commit_parsers = [
+    { body = ".*[dD]eprecate.*", group = "Deprecated" },
     { message = "^feat", group = "Added"},
     { message = "^fix", group = "Fixed"},
     { message = "^doc", group = "Documented"},
     { message = "^perf", group = "Performance"},
     { message = "^chore", skip = true },
     { message = "^test", skip = true },
-    { message = "prepare to release", skip = true }
+    { message = "prepare to release", skip = true },
 ]
 filter_commits = false
 # regex for preprocessing the commit messages

cordyceps/CHANGELOG.md

@@ -1,6 +1,11 @@
-## cordyceps-v0.2.1 - (2022-06-09)
+# Changelog
 
-[e3fe8f8](https://github.com/hawkw/mycelium/e3fe8f84212fa5c4ac5865d36a3cad9267c98c7c)...[dc2e638](https://github.com/hawkw/mycelium/dc2e638e056e183ac6eedfa7b821393f5447ba45)
+All notable changes to this project will be documented in this file.
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## cordyceps-v0.2.1 - (2022-06-9)
+
+[e3fe8f8](https://github.com/hawkw/mycelium/e3fe8f84212fa5c4ac5865d36a3cad9267c98c7c)...[7cdb821](https://github.com/hawkw/mycelium/7cdb82146fdddfa564d0ba78536da0b7579a63e0)
 
 
 ### Added