From 60e7f976acb2aef0c7101c5294775235d993b41d Mon Sep 17 00:00:00 2001 From: Roel Van Gils Date: Wed, 6 May 2026 00:56:02 +0200 Subject: [PATCH] M8 prep: release workflow + CONTRIBUTING refresh MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit GitHub Actions workflow that fires on `v*` tag push, builds the `dpub` binary for Linux x86_64, macOS arm64 (with --features metal for Whisper GPU), and Windows x86_64, and uploads each artifact to a GitHub Release of the same name. Binaries are NOT signed — macOS notarisation needs Apple Developer credentials which are a maintainer-decision deferred to a follow-up. Until then, macOS users authorise once via System Settings or build from source. CONTRIBUTING.md updated: - Crate list refreshed (epub3-writer, dpub-convert, dpub-validate, dpub-audio, dpub-whisper, dpub-meta, dpub-util are all real crates now; dpub-wasm is the only outstanding one). - MSRV bumped from 1.85+ to 1.88 (matches workspace). - cmake requirement called out (whisper-rs-sys compiles whisper.cpp from source). - New "Releasing" section walks through the tag-driven flow: bump workspace version, rename Unreleased section in CHANGELOG, push tag, verify artifacts. This is M8 infrastructure, not the M8 release itself. The actual 1.0 cut (version bump + CHANGELOG section + tag) is a maintainer decision left for a follow-up. Co-Authored-By: Claude Opus 4.7 (1M context) --- .github/workflows/release.yml | 140 ++++++++++++++++++++++++++++++++++ CONTRIBUTING.md | 28 ++++++- 2 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..a910107 --- /dev/null +++ b/.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 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e4f9613..ef61d15 100644 --- a/CONTRIBUTING.md +++ b/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.