From 7d1e6a9cb7b31eff7c5f35c40b6c674e2d22c00a Mon Sep 17 00:00:00 2001
From: shnewto <github@shnewto.dev>
Date: Sun, 12 Nov 2023 15:04:49 -0700
Subject: [PATCH] new release process using an action (and docs to go with it)

---
 .github/workflows/tag-and-publish-crate.yaml | 47 ++++++++++++++++++++
 Cargo.toml                                   |  2 +-
 RELEASE.md                                   | 22 +++++++++
 3 files changed, 70 insertions(+), 1 deletion(-)
 create mode 100644 .github/workflows/tag-and-publish-crate.yaml
 create mode 100644 RELEASE.md

diff --git a/.github/workflows/tag-and-publish-crate.yaml b/.github/workflows/tag-and-publish-crate.yaml
new file mode 100644
index 0000000..c39cb28
--- /dev/null
+++ b/.github/workflows/tag-and-publish-crate.yaml
@@ -0,0 +1,47 @@
+name: tag and publish crate [manual]
+
+on:
+  workflow_dispatch:
+    inputs:
+      tag-increment:
+        default: patch
+        required: true
+        type: choice
+        options:
+          - patch
+          - minor
+          - major
+
+jobs:
+  publish:
+    runs-on: macos-latest
+    permissions:
+      # Give the default GITHUB_TOKEN write permission to commit and push the
+      # added or changed files to the repository.
+      contents: write
+    steps:
+      - name: checkout repo
+        uses: actions/checkout@v2
+      - name: install stable toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+          override: true
+      - name: install rustfmt
+        run: rustup component add rustfmt
+      - name: rustfmt check
+        run: cargo fmt --all -- --check
+      - name: install clippy
+        run: rustup component add clippy
+      - name: cargo clippy
+        run: cargo clippy --all-features --all-targets
+      - name: cargo test
+        run: cargo test
+      - name: install cargo bump
+        run: cargo install cargo-bump
+      - name: bump version
+        run: cargo bump -g ${{ inputs.tag-increment }}
+      - name: push
+        run: git push && git push --tags
+      - name: cargo publish
+        run: cargo publish --token ${{ secrets.CRATES_TOKEN }}
diff --git a/Cargo.toml b/Cargo.toml
index a95270a..e4d6046 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,7 +1,7 @@
 [package]
 name = "ttaw"
 description = "talking to a wall, a piecemeal natural language processing library"
-
+# don't manually edit this version unless you're sure you want to circumvent the process documented in RELEASE.md
 version = "0.3.0"
 license = "MIT"
 
diff --git a/RELEASE.md b/RELEASE.md
new file mode 100644
index 0000000..f351979
--- /dev/null
+++ b/RELEASE.md
@@ -0,0 +1,22 @@
+# Release Process
+
+- leave the Cargo.toml package version alone :)
+- trigger the `tag and publish crate [manual]` action and specify the release increment (major, minor, or patch)
+  - once the action completes, the Cargo.toml will be updated and the crate will be live on crates.io
+- create a release (with title, notes, thanks, etc) and tie it to the tag that was created by the action / new crate version
+
+## Execution
+
+The order of operations for tagging and publishing in the action is this
+
+1. run all checks, i.e. fmt, clippy, tests, etc
+1. push change / update to the Cargo.toml
+1. push the new tag to the repo
+1. publish the new version to crates.io
+
+## Troubleshooting
+
+- if step 1 of execution fails, after addressing the error, you run the action again
+- if step 2 of execution fails, after addressing the error, you run the action again
+- if step 3 of execution fails (the Cargo.toml version was incremented), after addressing the error, you should manually tag (github's ux or the cli) and manually publish the crate with `cargo publish`
+- if step 4 of execution fails (the Cargo.toml version was incremented and there's a new corresponding tag), after addressing the error, you should manually publish the crate  with `cargo publish`