Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions .github/workflows/ci.yml → .github/workflows/default.yml
Original file line number Diff line number Diff line change
@@ -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.
Expand All @@ -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:
Expand Down
46 changes: 46 additions & 0 deletions .github/workflows/release.yml
Original file line number Diff line number Diff line change
@@ -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
11 changes: 11 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down Expand Up @@ -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).
77 changes: 77 additions & 0 deletions RELEASING.md
Original file line number Diff line number Diff line change
@@ -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.
Loading