diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8fa5efc..2dad952 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -49,6 +49,29 @@ jobs: fi echo "version=$NEW_VERSION" >> "$GITHUB_OUTPUT" + # Keeps the README's `pip`/`%pip install ...@vX.Y.Z[-staging]` example + # lines from ever going stale — only touches this branch's own lines + # (matched by the trailing `"` for main, `-staging"` for staging, so + # a staging run can never clobber main's line and vice versa). + # [skip ci]: this push must not re-trigger this same workflow. + - name: Update README's install examples for this branch + run: | + NEW_VERSION="${{ steps.version.outputs.version }}" + if [ "${{ github.ref_name }}" = "staging" ]; then + sed -i -E "s#(EEALakeHouse\.python\.git@v)[0-9]+\.[0-9]+\.[0-9]+(-staging\")#\1${NEW_VERSION}\2#g" README.md + else + sed -i -E "s#(EEALakeHouse\.python\.git@v)[0-9]+\.[0-9]+\.[0-9]+\"#\1${NEW_VERSION}\"#g" README.md + fi + if git diff --quiet -- README.md; then + echo "README already up to date for this branch's version." + else + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add README.md + git commit -m "Update README install examples to v${NEW_VERSION}${{ github.ref_name == 'staging' && '-staging' || '' }} [skip ci]" + git push + fi + # Tags the *build* (not the committed pyproject.toml) with its branch, # via a PEP 440 local version segment ("+main"/"+staging") — this is # what shows up in the wheel filename, e.g. diff --git a/README.md b/README.md index b8aa20c..08d902d 100644 --- a/README.md +++ b/README.md @@ -19,17 +19,20 @@ Two main class domains for the EEA data lakehouse: ## Install -[![Latest release](https://img.shields.io/github/v/release/eeadata/EEALakeHouse.python?label=latest%20release)](https://github.com/eeadata/EEALakeHouse.python/releases/latest) +[![main](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Feeadata%2FEEALakeHouse.python%2Freleases&query=%24%5B%3F%28%40.prerelease%3D%3Dfalse%29%5D.tag_name&label=main&color=blue)](https://github.com/eeadata/EEALakeHouse.python/releases/latest) +[![staging](https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fapi.github.com%2Frepos%2Feeadata%2FEEALakeHouse.python%2Freleases&query=%24%5B%3F%28%40.prerelease%3D%3Dtrue%29%5D.tag_name&label=staging&color=orange)](https://github.com/eeadata/EEALakeHouse.python/releases) -The badge above always shows the current latest release tag — substitute it for `v0.1.5` below -if it's moved on since this was written (or check the [Releases page](https://github.com/eeadata/EEALakeHouse.python/releases/latest) directly). +These badges are live — each one queries the GitHub API directly and always shows whatever tag +is *currently* released for that branch, updating on its own every time `main`/`staging` cuts a +new release (see [Releasing a new version](#releasing-a-new-version) — only one tag exists per +branch at a time, so pin to whatever the badge shows *now*, not a number copied from here). ```bash -# latest release (currently v0.1.5) — recommended: stable, pinned to a tag -pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@v0.1.5" +# main's latest release (stable) — pin to the tag the "main" badge above shows +pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@v0.1.6" -# latest main — bleeding edge, whatever's currently merged, not pinned to a release -pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@main" +# staging's latest release (early access) — pin to the tag the "staging" badge above shows +pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@v0.1.6-staging" ``` ## Usage @@ -182,17 +185,23 @@ previous release *and* tag first, so **tags aren't permanent** — pin to whatev [Install](#install) badge shows *now*, not to an old tag number, since it won't exist once a newer release replaces it. +The workflow also rewrites this README's `pip`/`%pip install ...@vX.Y.Z[-staging]` example lines +to the version it just released, committing that change back to the branch (`[skip ci]`, so it +doesn't re-trigger itself) — so the examples above never go stale, without anyone having to +remember to update them by hand. + ## Install in JupyterLab -Run this in a notebook cell — see the badge under [Install](#install) for the current latest -release tag (`v0.1.5` as of this writing): +Run this in a notebook cell (see the live badges under [Install](#install) for the current +`main`/`staging` release tags — the lines below are kept in sync with them automatically, see +[Releasing a new version](#releasing-a-new-version)): ```python -# latest release (currently v0.1.5) — recommended -%pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@v0.1.5" +# main's latest release (stable) — recommended +%pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@v0.1.6" -# latest main — bleeding edge, not pinned to a release -%pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@main" +# staging's latest release (early access) +%pip install "git+https://github.com/eeadata/EEALakeHouse.python.git@v0.1.6-staging" ``` Use the `%pip` magic rather than `!pip` — it installs into the kernel the @@ -208,5 +217,5 @@ Alternatively, download the wheel attached to the [GitHub Release page](https:// for that tag and install the local file instead of pulling from git: ```python -%pip install /path/to/EEADataLakehouse-0.1.5-py3-none-any.whl +%pip install /path/to/EEADataLakehouse--py3-none-any.whl ```