CI: Add a release preparation and release workflow (#1559)

* decouple versions again

* add prepare-release.yml

* add release.yml

* cleanup docs and publish.sh

* chore: change all variables into lower case

* chore: adjust to review

* chore: extend instructions for github release

* fix: update changes crates correctly

* ci: publish workspace on release

* chore: fixup release workflow

Author: photovoltex

.github/example/prepare-release.event

@@ -0,0 +1,6 @@
+{
+  "action": "workflow_dispatch",
+  "inputs": {
+      "versionBump": "minor"
+  }
+}

.github/scripts/bump-versions.sh

@@ -0,0 +1,69 @@
+#!/usr/bin/env bash
+
+# $fragment: see possible options https://github.com/christian-draeger/increment-semantic-version/tree/1.2.3?tab=readme-ov-file#version-fragment
+if [ "$fragment" = "" ]; then
+  fragment=$1
+fi
+
+allowed_crates="protocol oauth core discovery audio metadata playback connect"
+
+if [ "$fragment" = "patch" ]; then
+  last_tag=$(git describe --tags --abbrev=0)
+  awk_crates=$(echo "$allowed_crates" | tr ' ' '|')
+  diff_crates=$(git diff $last_tag... --stat --name-only \
+    | awk '/\.(rs|proto)$/{print}' \
+    | awk "/($awk_crates)\//{print}" \
+    | cut -d '/' -f 1 \
+    | uniq \
+    | tr \\n '\ ' \
+    | xargs )
+  echo "upgrading the following crates: [$diff_crates]"
+else
+  diff_crates=$allowed_crates
+  echo "upgrading all crates for consistency"
+fi
+
+# append bin so that the version of the binary is also bumped
+diff_crates="$diff_crates bin"
+
+# required by script as it's usually a github action
+export GITHUB_OUTPUT="version.txt"
+# https://github.com/christian-draeger/increment-semantic-version/tree/1.2.3
+increment_semver=$(curl https://raw.githubusercontent.com/christian-draeger/increment-semantic-version/refs/tags/1.2.3/entrypoint.sh)
+
+for diff_crate in $diff_crates ; do
+  if [ "$diff_crate" = "bin" ]; then
+    toml="./Cargo.toml"
+  else
+    toml="./$diff_crate/Cargo.toml"
+  fi
+
+  from="$(cat $toml | awk "/version/{print; exit}" | cut -d\" -f 2)"
+
+  # execute script inline, extract result and remove output file
+  echo "$increment_semver" | bash /dev/stdin $from $fragment
+  to=$(cat $GITHUB_OUTPUT | cut -d= -f 2)
+  rm $GITHUB_OUTPUT
+
+  echo "upgrading [librespot-$diff_crate] from [$from] to [$to]"
+
+  # replace version in associated diff_crate toml
+  sed -i "0,/$from/{s/$from/$to/}" $toml
+
+  if [ "$diff_crate" = "bin" ]; then
+    continue
+  fi
+
+  # update workspace dependency in root toml
+  sed -i "/librespot-$diff_crate/{s/$from/$to/}" ./Cargo.toml
+
+  # update related dependencies in diff_crate
+  for allowed_crate in $allowed_crates ; do
+    cat ./$allowed_crate/Cargo.toml | grep librespot-$diff_crate > /dev/null
+    if [ $? = 0 ]; then
+      sed -i "/librespot-$diff_crate/{s/$from/$to/}" ./$allowed_crate/Cargo.toml
+    fi
+  done
+done
+
+exit 0

.github/workflows/build.yml

@@ -12,7 +12,6 @@ name: build
       - "LICENSE"
       - "*.sh"
       - "**/Dockerfile*"
-      - "publish.sh"
       - "test.sh"
   pull_request:
     paths-ignore:
@@ -22,7 +21,6 @@ name: build
       - "LICENSE"
       - "*.sh"
       - "**/Dockerfile*"
-      - "publish.sh"
       - "test.sh"
   schedule:
     # Run CI every week

.github/workflows/prepare-release.yml

@@ -0,0 +1,57 @@
+---
+# test with
+# act --job prepare-release --eventpath ./.github/example/prepare-release.event
+name: prepare release
+on:
+  workflow_dispatch:
+    inputs:
+      versionBump:
+        description: "Version bump for"
+        required: true
+        type: choice
+        options:
+          - major
+          - minor
+          - patch
+
+jobs:
+  prepare-release:
+    name: Prepare release
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+        with:
+          fetch-tags: true
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Bump versions
+        env:
+          fragment: ${{ github.event.inputs.versionBump }}
+        run: ./.github/scripts/bump-versions.sh
+
+      - name: Update Cargo.lock
+        run: cargo update --workspace
+
+      - name: Get binary version
+        id: get-version
+        run: |
+          VERSION=$(cat ./Cargo.toml | awk "/version/{print; exit}" | cut -d\" -f 2)
+          echo VERSION=$VERSION >> ${GITHUB_OUTPUT}
+
+      - name: Update Changelog
+        uses: thomaseizinger/[email protected]
+        with:
+          tag: v${{ steps.get-version.outputs.VERSION }}
+          version: ${{ steps.get-version.outputs.VERSION }}
+
+      - name: Commit version prepare
+        uses: stefanzweifel/git-auto-commit-action@v6
+        if: ${{ !env.ACT }}
+        with:
+          commit_message: 'Prepare for v${{ steps.get-version.outputs.VERSION }} release'
+          file_pattern: '*.md *.toml *.lock'

.github/workflows/release.yml

@@ -0,0 +1,34 @@
+name: release.yml
+on:
+  release:
+    types:
+      - created
+  workflow_dispatch:
+
+jobs:
+  publish-crates:
+    name: Publish librespot
+    runs-on: ubuntu-latest
+    permissions: 
+      contents: read
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+
+      - name: Cache Rust dependencies
+        uses: Swatinem/rust-cache@v2
+
+      - name: Install dependencies
+        run: sudo apt-get update && sudo apt-get install -y libasound2-dev
+
+      - name: Verify librespot workspace
+        run: cargo publish --workspace --dry-run
+
+      - name: Publish librespot workspace
+        if: ${{ !env.ACT }}
+        env:
+          CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        run: cargo publish --workspace --no-verify

CHANGELOG.md

@@ -178,7 +178,7 @@ will be well worth it.
 
 All these changes are likely to introduce new bugs as well as some regressions.
 We appreciate all your testing and contributions to the repository:
-https://github.com/librespot-org/librespot
+<https://github.com/librespot-org/librespot>
 
 ### Changed
 

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "librespot"
-version.workspace = true
+version = "0.7.1"
 rust-version.workspace = true
 authors.workspace = true
 license.workspace = true
@@ -29,7 +29,6 @@ include = [
 ]
 
 [workspace.package]
-version = "0.7.1"
 rust-version = "1.85"
 authors = ["Librespot Org"]
 license = "MIT"

PUBLISHING.md

@@ -2,42 +2,41 @@
 
 ## How To
 
-Read through this paragraph in its entirety before running anything.
+1. [prepare the release](#prepare-the-release)
+2. [create a github-release](#creating-a-github-release)
 
-The Bash script in the root of the project, named `publish.sh` can be used to publish a new version of librespot and its corresponding crates. the command should be used as follows from the project root: `./publish 0.1.0` from the project root, substituting the new version number that you wish to publish. *Note the lack of a v prefix on the version number. This is important, do not add one.* The v prefix is added where appropriate by the script.
+### Prepare the release
 
-Make sure that you are are starting from a clean working directory for both `dev` and `master`, completely up to date with remote and all local changes either committed and pushed or stashed.
+For preparing the release a manuel workflow should be available that takes care of the common preparation. But 
+this can also be done manually if so desired. The workflow does:
+- upgrade the version according to the targeted release (`major`, `minor`, `patch`)
+  - `major` and `minor` require all crates to be updated
+  - `patch` instead only upgrades the crates that had any changes
+- updates the changelog according to Keep-A-Changelog convention
+- commits and pushes the changes to remote
 
-Note that the script will update the crates and lockfile, so in case you did not do so before, you really should to make sure none of the dependencies introduce some SemVer breaking change. Then commit so you again have a clean working directory.
+### Creating a github-release
 
-Also don't forget to update `CHANGELOG.md` with the version number, release date, and at the bottom the comparison links.
+After everything is prepared for the new version. A [new release can be created](https://github.com/librespot-org/librespot/releases/new) 
+from the ui. The tag will not be available as it isn't set by the prepare workflow, so a new tag needs to be created.
 
-You will want to perform a dry run first: `./publish --dry-run 0.1.0`. Please make note of any errors or warnings. In particular, you may need to explicitly inform Git which remote you want to track for the `master` branch like so: `git --track origin/master` (or whatever you have called the `librespot-org` remote `master` branch).
+The tag and name of the release should be named like `v<version>` where `version` is the version of the binary to be
+published. As release notes, copy the entries from the changelog for this release.
 
-Depending on your system the script may fail to publish the main `librespot` crate after having published all the `librespot-xyz` sub-crates. If so then make sure the working directory is committed and pushed (watch `Cargo.toml`) and then run `cargo publish` manually after `publish.sh` finished.
+The release should be created as draft, which will trigger the workflow that will publish the changed crates and binary.
+The workflow will:
+- check if all crates needs to be published or only certain crates
+- publish the crates in a specific order while excluding crates that didn't have any changes
+- publish the binary
 
-To publish the crates your GitHub account needs to be authorized on `crates.io` by `librespot-org`. First time you should run `cargo login` and follow the on-screen instructions.
-
-## What the script does
-
-This is briefly how the script works:
-
-  - Change to branch master, pull latest version, merge development branch.
-  - Change to working directory.
-  - Change version number in all files.
-  - Update crates and lockfile.
-  - Commit and tag changes.
-  - Publish crates in given order.
-  - Push version commit and tags to master.
+After the workflow was successful the version can be published.
 
 ## Notes
 
-Publishing librespot to crates.io is a slightly convoluted affair due to the various dependencies that each package has on other local packages. The order of publising that has been found to work is as follows:
-
-`protocol -> core -> audio -> metadata -> playback -> connect -> librespot`
-
-The `protocol` package needs to be published with `cargo publish --no-verify` due to the build script modifying the source during compile time.
-
-Publishing can be done using the command `cargo publish` in each of the directories of the respective crate.
+Publishing librespot to crates.io is a slightly convoluted affair due to the various dependencies that each package has 
+on other local packages. The order of publishing that has been found to work is as follows:
+> `protocol -> core -> audio -> metadata -> playback -> connect -> librespot`
 
-The script is meant to cover the standard publishing process. There are various improvements that could be made, such as adding options such as the user being able to add a changelog, though this is not the main focus, as the script is intended to be run by a CI. Feel free to improve and extend functionality, keeping in mind that it should always be possible for the script to be run in a non-interactive fashion.
+The `protocol` package needs to be published with `cargo publish --no-verify` due to the build script modifying the 
+source during compile time. Publishing can be done using the command `cargo publish` in each of the directories of the 
+respective crate.

audio/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "librespot-audio"
-version.workspace = true
+version = "0.7.1"
 rust-version.workspace = true
 authors = ["Paul Lietar <[email protected]>"]
 license.workspace = true

connect/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "librespot-connect"
-version.workspace = true
+version = "0.7.1"
 rust-version.workspace = true
 authors = ["Paul Lietar <[email protected]>"]
 license.workspace = true