M8 prep: release workflow + CONTRIBUTING refresh

.github/workflows/release.yml

@@ -0,0 +1,140 @@
+name: Release
+
+# Triggered by pushing a `v*` tag (e.g. `v0.5.0`, `v1.0.0`). Builds the
+# `dpub` binary on every supported platform and uploads each artifact
+# to a GitHub Release.
+#
+# Binaries are NOT signed in this workflow. macOS code signing +
+# notarisation requires Apple Developer credentials that have to live
+# in repo secrets; that work is deferred until the maintainer is
+# ready to manage those secrets. Until then, macOS users will need
+# to authorise the binary manually under System Settings → Privacy &
+# Security on first run, or build from source.
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: 'Tag to release (must already exist on `main`)'
+        required: true
+
+env:
+  CARGO_TERM_COLOR: always
+  RUSTFLAGS: -D warnings
+
+jobs:
+  build:
+    name: build (${{ matrix.target }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - target: x86_64-unknown-linux-gnu
+            os: ubuntu-latest
+            extra_features: ""
+            archive_ext: tar.gz
+          - target: aarch64-apple-darwin
+            os: macos-latest
+            extra_features: "metal"
+            archive_ext: tar.gz
+          - target: x86_64-pc-windows-msvc
+            os: windows-latest
+            extra_features: ""
+            archive_ext: zip
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install cmake (Linux)
+        if: matrix.os == 'ubuntu-latest'
+        run: sudo apt-get update && sudo apt-get install -y cmake
+
+      - name: Install cmake (macOS)
+        if: matrix.os == 'macos-latest'
+        run: brew install cmake
+
+      # Windows runners ship cmake by default.
+
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: ${{ matrix.target }}
+
+      - uses: Swatinem/rust-cache@v2
+
+      - name: Build
+        shell: bash
+        run: |
+          features=""
+          if [ -n "${{ matrix.extra_features }}" ]; then
+            features="--features ${{ matrix.extra_features }}"
+          fi
+          cargo build --release -p dpub-cli --target ${{ matrix.target }} $features
+
+      - name: Stage artifact
+        id: stage
+        shell: bash
+        run: |
+          mkdir -p staging
+          binary_name="dpub"
+          if [ "${{ matrix.os }}" = "windows-latest" ]; then
+            binary_name="dpub.exe"
+          fi
+          src="target/${{ matrix.target }}/release/${binary_name}"
+          tag_name="${GITHUB_REF_NAME}"
+          if [ -z "${tag_name}" ]; then
+            tag_name="${{ inputs.tag }}"
+          fi
+          stem="dpub-${tag_name}-${{ matrix.target }}"
+          cp "$src" "staging/${binary_name}"
+          cp README.md LICENSE-APACHE LICENSE-MIT CHANGELOG.md staging/
+
+          cd staging
+          if [ "${{ matrix.archive_ext }}" = "zip" ]; then
+            7z a "../${stem}.zip" *
+            echo "asset=${stem}.zip" >> "$GITHUB_OUTPUT"
+          else
+            tar -czf "../${stem}.tar.gz" *
+            echo "asset=${stem}.tar.gz" >> "$GITHUB_OUTPUT"
+          fi
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: ${{ steps.stage.outputs.asset }}
+          path: ${{ steps.stage.outputs.asset }}
+          if-no-files-found: error
+
+  publish:
+    name: publish release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Resolve tag
+        id: tag
+        shell: bash
+        run: |
+          if [ -n "${{ inputs.tag }}" ]; then
+            echo "tag=${{ inputs.tag }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create / update release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ steps.tag.outputs.tag }}
+          name: ${{ steps.tag.outputs.tag }}
+          generate_release_notes: true
+          files: artifacts/*
+          fail_on_unmatched_files: true

CONTRIBUTING.md

@@ -11,7 +11,7 @@ Thanks for your interest! dpub is in early development. Bug reports, design feed
 
 ## Development setup
 
-You need a recent stable Rust toolchain (1.85+, Edition 2024).
+You need a recent stable Rust toolchain (MSRV 1.88, Edition 2024) and `cmake` for the bundled `dpub-whisper` crate (the `whisper-rs-sys` dep compiles whisper.cpp from source).
 
 ```sh
 git clone https://github.com/11ways/dpub
@@ -20,6 +20,8 @@ cargo build
 cargo test
 ```
 
+Several optional dev tools turn on additional integration tests; see the table in [`README.md`](README.md#local-development).
+
 Optional but recommended for local validation parity with CI:
 
 ```sh
@@ -30,9 +32,16 @@ cargo clippy --all-targets -- -D warnings
 ## Project structure
 
 - `crates/dpub-core/` — DAISY 2.02 in-memory model and parser. No I/O beyond reading input files.
-- `crates/dpub-cli/` — the `dpub` binary. User-facing concerns only; logic lives in core / domain crates.
+- `crates/epub3-writer/` — typed EPUB 3 model and ZIP serialiser (Media Overlays, cover image).
+- `crates/dpub-convert/` — drives the DAISY 2.02 → EPUB 3 pipeline.
+- `crates/dpub-validate/` — EPUBCheck and ACE wrappers, structured `Report`.
+- `crates/dpub-audio/` — ffmpeg-driven MP3 → Opus re-encoder.
+- `crates/dpub-whisper/` — local Whisper transcription via whisper.cpp FFI.
+- `crates/dpub-meta/` — external metadata lookup (currently Open Library covers).
+- `crates/dpub-util/` — small shared helpers (XML escaping).
+- `crates/dpub-cli/` — the `dpub` binary. User-facing concerns only; logic lives in the domain crates.
 
-Future crates (`epub3-writer`, `dpub-validate`, `dpub-audio`, `dpub-whisper`, `dpub-wasm`) are introduced milestone by milestone.
+`dpub-wasm` is the next planned crate (M7).
 
 ## Testing
 
@@ -59,6 +68,19 @@ Optional body explaining the *why* if it isn't obvious from the diff.
 Reference issues with `Refs #N` or `Closes #N`.
 ```
 
+## Releasing
+
+Releases are cut by tag. The [`.github/workflows/release.yml`](.github/workflows/release.yml) workflow fires on any `v*` tag push and builds the `dpub` binary for Linux (x86_64), macOS (arm64, with Metal Whisper acceleration), and Windows (x86_64); it then uploads each as an asset on a GitHub Release of the same name.
+
+To cut a release:
+
+1. Bump `version` in the workspace `Cargo.toml` (e.g. `0.1.0-dev` → `0.5.0`).
+2. Update `CHANGELOG.md`: rename the `[Unreleased]` section to the new version with today's date, and add a fresh empty `[Unreleased]` block above it.
+3. Commit on `main` (via PR) and tag: `git tag v0.5.0 && git push origin v0.5.0`.
+4. Wait for the workflow to finish; verify the artifacts attached to the release page work on each platform.
+
+Binaries from this workflow are **not signed**. macOS code signing + notarisation requires Apple Developer credentials in repo secrets, which is deferred until the project commits to that maintenance burden.
+
 ## Licensing of contributions
 
 By submitting a contribution to this project, you agree to license your contribution under the same terms as dpub itself: dual MIT / Apache-2.0. No CLA is required.