diff --git a/.github/workflows/ci.yml b/.github/workflows/default.yml similarity index 94% rename from .github/workflows/ci.yml rename to .github/workflows/default.yml index addb20d..1ec5951 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/default.yml @@ -1,4 +1,4 @@ -name: CI +name: Checks # Changes reach main only through pull requests, so CI runs on those. Use "Run workflow" in the # Actions tab to run it on any branch by hand. @@ -8,7 +8,7 @@ on: # A new push to a pull request cancels the run for its previous commit. concurrency: - group: ci-${{ github.event.pull_request.number || github.ref }} + group: checks-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: true jobs: diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..a19c511 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,46 @@ +name: Release + +# Publishing a GitHub release builds the wheel and sdist, checks them, and attaches them to it. +on: + release: + types: [published] + +permissions: + contents: write # needed to upload release assets + +jobs: + build: + runs-on: ubuntu-latest + env: + TAG: ${{ github.event.release.tag_name }} + steps: + - uses: actions/checkout@v4 + - uses: astral-sh/setup-uv@v6 + with: + python-version: "3.13" + + # A release tagged v0.2.0 must ship version 0.2.0, or the wheel name lies. + - name: Check tag matches project version + run: | + version="$(uv version --short)" + if [ "${TAG#v}" != "$version" ]; then + echo "::error::Tag $TAG does not match pyproject version $version" + exit 1 + fi + + - run: uv sync --frozen + - run: uv run --frozen pytest + - run: uv build + + # Install the built wheel into a clean venv, without uv's project env, and run it. + - name: Smoke-test the wheel + run: | + uv venv "$RUNNER_TEMP/venv" + uv pip install --python "$RUNNER_TEMP/venv" dist/*.whl + "$RUNNER_TEMP/venv/bin/memmap" guide > /dev/null + "$RUNNER_TEMP/venv/bin/memmap" check examples/custom_bootloader.yaml --strict + + - name: Attach to release + env: + GH_TOKEN: ${{ github.token }} + run: gh release upload "$TAG" dist/* --clobber diff --git a/README.md b/README.md index 9870770..98b0f1f 100644 --- a/README.md +++ b/README.md @@ -15,6 +15,15 @@ Below find an example with four memory maps drawn by **memmap**. ## Install +Each [GitHub release](https://github.com/iharhl/memmap/releases) has a wheel attached. To install +it with Python 3.10 or newer and no uv or checkout, using the version you want: + +```bash +pipx install https://github.com/iharhl/memmap/releases/download/v0.2.0/memmap-0.2.0-py3-none-any.whl +``` + +To work from a checkout: + ```bash uv sync ``` @@ -141,3 +150,5 @@ MEMMAP_UPDATE_GOLDEN=1 uv run pytest tests/test_golden.py Text is measured with a built-in Helvetica/Arial width table, so wrapping is slightly approximate for other fonts. + +To cut a release, see [RELEASING.md](RELEASING.md). diff --git a/RELEASING.md b/RELEASING.md new file mode 100644 index 0000000..bdeb521 --- /dev/null +++ b/RELEASING.md @@ -0,0 +1,77 @@ +# Releasing memmap + +A release is a GitHub release with the wheel and sdist attached. Publishing the release runs +[`release.yml`](.github/workflows/release.yml), which builds both files, checks them and uploads +them. Nothing is published to PyPI. + +## 1. Bump the version + +`main` is protected, so the bump goes through a pull request like any other change. + +```bash +git switch main && git pull +``` + +```bash +git switch -c release/v0.2.0 +``` + +```bash +uv version --bump minor +``` + +`--bump` takes `patch` (0.1.0 to 0.1.1), `minor` (0.1.0 to 0.2.0) or `major` (0.1.0 to 1.0.0). It +updates `version` in `pyproject.toml` and in `uv.lock`. Commit both, push, open a pull request and +merge it once the checks pass. + +## 2. Publish the release + +From the terminal: + +```bash +gh release create v0.2.0 --target main --generate-notes +``` + +Or on GitHub, under Releases, choose "Draft a new release": +- Tag: type `v0.2.0` and pick "Create new tag on publish". +- Target: `main`. +- "Generate release notes" lists the pull requests merged since the last release. +- "Publish release". + +The tag is `v` followed by the version in `pyproject.toml`. A draft release does not start the +workflow until it is published. A pre-release does. + +## 3. What the workflow does + +1. Fails if the tag without its `v` differs from the version in `pyproject.toml`. +2. Runs `pytest`. +3. Builds `memmap-0.2.0-py3-none-any.whl` and `memmap-0.2.0.tar.gz`. +4. Installs the wheel in a clean venv and runs `memmap guide` and `memmap check` from it. +5. Uploads both files to the release's Assets. + +It takes about a minute. Follow it in the Actions tab. + +## 4. Install a release + +```bash +pipx install https://github.com/iharhl/memmap/releases/download/v0.2.0/memmap-0.2.0-py3-none-any.whl +``` + +`pip install` with the same URL works too. Add `[raster]` after the file name for PNG and PDF +output, which also needs the system cairo library. + +## When something fails + +- **Tag and version differ**, for example because the bump was not merged: nothing was built. + Delete the release and its tag, merge the bump, and publish again. + + ```bash + gh release delete v0.2.0 --cleanup-tag + ``` + +- **A later step fails**: the release stays published without assets. Fix the cause and choose + "Re-run jobs" on the failed run. The upload replaces files already attached. + +GitHub runs the workflow file as it is in the tagged commit, so a fix to `release.yml` itself only +applies to releases tagged after that fix is merged. For an older tag, delete the release and tag +and publish again on a newer commit.