diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 5c3b0bfa..0c792e96 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -1700,6 +1700,10 @@ jobs: with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./book + # 'latest' docs stay at the site root (existing URLs unaffected). + # keep_files preserves the per-release /vX.Y.Z/ subdirs that + # release.yml publishes — a plain deploy would wipe them. + keep_files: true # CVC reference simulation for timing correctness validation cvc-reference: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d82cd14e..bcbc7009 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -129,6 +129,7 @@ jobs: id: notes env: IS_PRERELEASE: ${{ steps.meta.outputs.is_prerelease }} + TAG: ${{ github.ref_name }} run: | set -euo pipefail ver="${{ steps.meta.outputs.version }}" @@ -147,6 +148,15 @@ jobs: echo "no [$ver] section; prerelease → using [Unreleased] draft notes" >&2 extract "Unreleased" > notes.md || true fi + # Version-pin doc links: rewrite `docs/foo.md` refs to the mdBook page + # published for THIS release (docs-version job deploys to gh-pages + # //). Produces a clickable [docs/foo.md](…//foo.html). \x60 + # is a backtick (kept out of the raw shell to avoid interpolation). + if [ -s notes.md ]; then + sed -i -E \ + "s#\x60docs/([A-Za-z0-9/_-]+)\.md\x60#[docs/\1.md](https://gpu-eda.github.io/Jacquard/${TAG}/\1.html)#g" \ + notes.md + fi if [ ! -s notes.md ]; then echo "no matching CHANGELOG section; using auto-generated notes" >&2 echo "AUTO=true" >> "$GITHUB_OUTPUT" @@ -276,3 +286,33 @@ jobs: git commit -m "jacquard ${TAG#v}" git push echo "Pushed jacquard ${TAG#v} to ${tap_repo}." + + # Publish a frozen copy of the docs for this release to gh-pages //, so + # the release notes can link to version-pinned mdBook pages (the site root + # tracks main / "latest"). `keep_files: true` on both this deploy and the + # main-branch deploy (ci.yml) means version subdirs accumulate without + # wiping each other. Runs for real tags only (skips workflow_dispatch + # dry-runs, whose ref is a branch); independent of the binary build. + docs-version: + name: Publish versioned docs + if: startsWith(github.ref, 'refs/tags/v') + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + submodules: false + - name: Install mdbook + run: | + mkdir -p ~/.cargo/bin + curl -sSL https://github.com/rust-lang/mdBook/releases/download/v0.4.44/mdbook-v0.4.44-x86_64-unknown-linux-gnu.tar.gz \ + | tar -xz -C ~/.cargo/bin + echo "$HOME/.cargo/bin" >> "$GITHUB_PATH" + - name: Build mdbook + run: mdbook build + - name: Deploy versioned docs to gh-pages // + uses: peaceiris/actions-gh-pages@v4 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./book + destination_dir: ${{ github.ref_name }} + keep_files: true diff --git a/CHANGELOG.md b/CHANGELOG.md index 81dd0e84..9a0c3545 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,13 @@ the public contracts in `docs/release-process.md` follow stricter rules). ## [Unreleased] +A substantial feature release: a **behavioral-RTL on-ramp** (synthesize Verilog / +SystemVerilog directly, no external tools), a complete **cell-model IR** that +makes the binary self-contained for standard cells and adds SKY130 + IHP SG13G2, +**plural QSPI memory with a writable PSRAM mode** across Metal / CUDA / HIP, and +new **GPU frame-capture** + **device-timestamp cosim profiling**. Full detail +below; docs links point to the version-pinned pages for this release. + ### Added - **Behavioral-RTL on-ramp (ADR 0021).** `jacquard sim` and `jacquard cosim` diff --git a/docs/release-process.md b/docs/release-process.md index 62d0d394..45f98f12 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -92,6 +92,26 @@ placeholder the job overwrites. Requires the one-time org setup: `secrets.HOMEBREW_TAP_TOKEN` (a token with `contents: write` on both tap repos) and the `gpu-eda/homebrew-tap-prerelease` repo. +## Release notes & versioned docs (automated) + +Release notes come from the CHANGELOG, and doc links are pinned to the release +— both automatic in `release.yml`: + +- **Notes body** = the CHANGELOG section for the tag's version. A prerelease + (`X.Y.Z-rc.N`) has no dated section, so the extractor falls back to + `[Unreleased]` — RCs ship the same curated draft you'll ship at promotion. + So: **write the notes in `[Unreleased]`**, including a one-sentence summary + lead-in before `### Added` (it becomes the release intro). +- **Doc links are version-pinned.** The extractor rewrites `` `docs/foo.md` `` + references into `[docs/foo.md](https://gpu-eda.github.io/Jacquard//foo.html)` + — the mdBook page frozen for *this* release. So keep CHANGELOG doc references + as repo-relative `` `docs/foo.md` `` (clean in-repo); the workflow does the + URL rewrite. +- **Versioned docs deploy.** The `docs-version` job publishes the book to + gh-pages `/(tag)/` on every release tag (`keep_files: true`), while the + `main` push keeps deploying "latest" to the site root. Version subdirs + accumulate side by side; the pinned links above resolve to them. + ## Staging validation (release candidates) Optional but recommended before a user-facing release: prove the