From e2d030d62e0aae5a2ca21d77ce774cfacc0b24fc Mon Sep 17 00:00:00 2001 From: Cameron DeCoster Date: Wed, 18 Nov 2026 10:54:33 -0700 Subject: [PATCH 1/5] Rename workflow --- .github/workflows/{publish_testpypi.yml => test_and_build.yml} | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .github/workflows/{publish_testpypi.yml => test_and_build.yml} (100%) diff --git a/.github/workflows/publish_testpypi.yml b/.github/workflows/test_and_build.yml similarity index 100% rename from .github/workflows/publish_testpypi.yml rename to .github/workflows/test_and_build.yml From fecf4d68e41cb2176219b086197a2946f1b77068 Mon Sep 17 00:00:00 2001 From: Cameron DeCoster Date: Wed, 18 Nov 2026 10:56:42 -0700 Subject: [PATCH 2/5] Pin actions and remove TestPyPI publishing --- .github/workflows/test_and_build.yml | 42 +++------------------------- 1 file changed, 4 insertions(+), 38 deletions(-) diff --git a/.github/workflows/test_and_build.yml b/.github/workflows/test_and_build.yml index c99fb64a..34f29461 100644 --- a/.github/workflows/test_and_build.yml +++ b/.github/workflows/test_and_build.yml @@ -1,6 +1,6 @@ -# .github/workflows/publish_testpypi.yml +# .github/workflows/test_and_build.yml --- -name: test-n-build +name: test-and-build on: workflow_dispatch: push: @@ -22,10 +22,10 @@ jobs: env: UV_PYTHON: ${{ matrix.python_v }} steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 1 - - uses: astral-sh/setup-uv@v5 + - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 - name: Install Dependencies if: ${{ matrix.os == 'ubuntu-latest' }} run: sudo apt-get update && sudo apt-get install xvfb @@ -77,37 +77,3 @@ jobs: if: ${{ runner.debug && matrix.os == 'ubuntu-latest' }} run: xvfb-run uv run --no-sync poe debug-test timeout-minutes: 8 - - testpypi-publish: - defaults: - run: - working-directory: ./src/py/ - name: Upload release to TestPyPI - needs: super-test - if: ${{ !cancelled() && - !failure() && - github.event_name == 'push' && - github.run_attempt == 1 }} - runs-on: ubuntu-latest - environment: - name: testpypi - url: https://test.pypi.org/p/kaleido - # Signs this workflow so pypi trusts it - permissions: - id-token: write - steps: - - name: Checkout - uses: actions/checkout@v4 - - uses: astral-sh/setup-uv@v5 - - uses: actions/setup-python@v5 - with: - python-version-file: "./src/py/pyproject.toml" - - run: git checkout ${{ github.ref_name }} - - run: uv sync --frozen --all-extras - - run: uv build - - name: Publish package distributions to PyPI - uses: pypa/gh-action-pypi-publish@release/v1 - with: - repository-url: https://test.pypi.org/legacy/. - packages-dir: src/py/dist - verbose: true From 2129f76a6d34a35c3cf0bb28aa1a5387116045c4 Mon Sep 17 00:00:00 2001 From: Cameron DeCoster Date: Wed, 18 Nov 2026 11:00:21 -0700 Subject: [PATCH 3/5] Add PyPI publishing workflow --- .github/workflows/publish_pypi.yml | 52 ++++++++++++++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 .github/workflows/publish_pypi.yml diff --git a/.github/workflows/publish_pypi.yml b/.github/workflows/publish_pypi.yml new file mode 100644 index 00000000..afa8445a --- /dev/null +++ b/.github/workflows/publish_pypi.yml @@ -0,0 +1,52 @@ +# .github/workflows/publish_pypi.yml +--- +name: publish-pypi +on: + workflow_dispatch: + inputs: + tag: + description: Tag to publish (for example v1.6.0) + required: true + type: string +jobs: + pypi-publish: + name: Upload release to PyPI + runs-on: ubuntu-latest + defaults: + run: + working-directory: ./src/py/ + environment: + name: pypi + url: https://pypi.org/p/kaleido + # Signs this workflow so pypi trusts it + permissions: + id-token: write + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.tag }} + # setuptools-git-versioning reads the tags to set the version + fetch-depth: 0 + - uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2 # v10.3.3 + - run: uv sync --locked --all-extras --no-sources + - run: git diff --quiet HEAD || { echo "Working tree dirty"; exit 1; } + - run: uv build + - name: Verify that the build matches the tag + run: | + expected="${{ inputs.tag }}" + expected="${expected#v}" + wheel="dist/kaleido-$expected-py3-none-any.whl" + sdist="dist/kaleido-$expected.tar.gz" + if [ ! -f "$wheel" ] || [ ! -f "$sdist" ]; then + echo "Expected version $expected, but dist/ holds:" + ls -1 dist/ + exit 1 + fi + echo "Built $expected from ${{ inputs.tag }}" + - name: Publish package distributions to PyPI + uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 + with: + packages-dir: src/py/dist + # A re-run of a tag already on PyPI skips instead of failing + skip-existing: true From 77dd7638c2c87b4cd38ad6f2d91c0b22deddc503 Mon Sep 17 00:00:00 2001 From: Cameron DeCoster Date: Wed, 18 Nov 2026 11:00:28 -0700 Subject: [PATCH 4/5] Update release docs --- RELEASE.md | 49 ++++++++++++++----------------------------------- 1 file changed, 14 insertions(+), 35 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index e5ffab48..269fa8d9 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -4,8 +4,9 @@ Follow the steps in this document to release a new version of Kaleido. ## Overview -- Versions are determined automatically from git tags by `setuptools-git-versioning`. There is no hard-coded version string to update. Pushing a `v*` tag triggers CI, which tests and publishes the package to TestPyPI. -- Publishing to PyPI and creating a GitHub release are done manually. +- Versions are determined automatically from git tags by `setuptools-git-versioning`. There is no hard-coded version string to update. Pushing a `v*` tag starts the `test-and-build` workflow, which builds and tests the package on each platform. That workflow publishes nothing. +- The `publish-pypi` workflow uploads the package to PyPI with trusted publishing (OIDC). A maintainer starts the workflow by hand, so no API token is necessary. +- Creating a GitHub release is done manually. ## Release steps @@ -29,41 +30,19 @@ Follow the steps in this document to release a new version of Kaleido. git tag vX.Y.Z git push origin vX.Y.Z ``` -5. Build the release artifacts: - - - [Install `uv`](https://docs.astral.sh/uv/getting-started/installation/) if not already installed on your machine - - - Ensure your git environment inside the `Kaleido/` directory is totally clean, i.e. `git status` returns the following: - - ``` - On branch main - Your branch is up to date with 'origin/main'. - - nothing to commit, working tree clean - ``` - - - If needed, stash or delete/move files to get to a clean environment. This is important because `setuptools-git-versioning` will not generate the correct version number if you have untracked or changed files present. - - - Build the package: - ``` - cd src/py/ - uv build - ``` - - Two artifacts will be added to `src/py/dist`. Ensure that they have the correct filenames: - - `kaleido-X.Y.Z-py3-none-any.whl` - - `kaleido-X.Y.Z.tar.gz` -6. Release on GitHub: +5. Watch the `test-and-build` workflow: + - The tag push starts `.github/workflows/test_and_build.yml` + - The workflow builds the package on Linux, Windows, and macOS for each supported Python version, then runs the tests against the built wheel + - If the workflow fails, read the failure before you continue. A flaky browser test does not block the release, but a build failure does. +6. Release on PyPI: + - Open the Actions tab and select `publish-pypi` + - Select "Run workflow", enter the tag (for example `vX.Y.Z`), and start the run + - Open the run and approve the deployment under "Review deployments" + - The `pypi` environment needs a review from the `plotly/libraries_admin` team. The job waits for that approval before GitHub issues the OIDC token, so an unapproved run never reaches PyPI. + - The workflow checks out the tag, builds the package, and confirms that the built version matches the tag. The upload uses `skip-existing`, so a second run of the same tag skips the files that PyPI holds already. +7. Release on GitHub: - Go to https://github.com/plotly/Kaleido/releases and click "Draft a new release" - Select the `vX.Y.Z` tag you created previously - Copy and paste the relevant changelog section into the release notes - - Upload the `.whl` and `.tar.gz` build artifacts -7. Release on PyPI: - - Install the `twine` Python package if not already installed (`pip install twine`) - - `cd` into the `dist/` directory - - Use `twine` to upload the artifacts to PyPI: - ``` - twine upload kaleido-X.Y.Z* - ``` - - You will need to enter an API token proving you have permission to publish That's it! Make sure to visit https://pypi.org/project/kaleido to verify that the new package version is available. From b905d00603aafd554c75ed4b691770c6fb0363ed Mon Sep 17 00:00:00 2001 From: Cameron DeCoster Date: Wed, 18 Nov 2026 12:48:41 -0700 Subject: [PATCH 5/5] Add GH release job to workflow --- .github/workflows/publish_pypi.yml | 68 ++++++++++++++++++++++++++++++ RELEASE.md | 23 +++++----- 2 files changed, 80 insertions(+), 11 deletions(-) diff --git a/.github/workflows/publish_pypi.yml b/.github/workflows/publish_pypi.yml index afa8445a..18081928 100644 --- a/.github/workflows/publish_pypi.yml +++ b/.github/workflows/publish_pypi.yml @@ -8,6 +8,10 @@ on: description: Tag to publish (for example v1.6.0) required: true type: string +# A second run of the same tag waits for the first run to finish +concurrency: + group: publish-${{ inputs.tag }} + cancel-in-progress: false jobs: pypi-publish: name: Upload release to PyPI @@ -44,9 +48,73 @@ jobs: exit 1 fi echo "Built $expected from ${{ inputs.tag }}" + # The github-release job attaches these same files to the release + - uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: dist + path: src/py/dist/ + if-no-files-found: error - name: Publish package distributions to PyPI uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3 with: packages-dir: src/py/dist # A re-run of a tag already on PyPI skips instead of failing skip-existing: true + + github-release: + name: Create GitHub release + needs: pypi-publish + runs-on: ubuntu-latest + # Kept apart from pypi-publish so that the OIDC token and the write + # access to the repository never share a job + permissions: + contents: write + env: + GH_TOKEN: ${{ github.token }} + TAG: ${{ inputs.tag }} + steps: + - name: Checkout + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + ref: ${{ inputs.tag }} + - uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2 + with: + name: dist + path: dist/ + - name: Extract release notes from CHANGELOG.md + run: | + # Print the lines under "## " up to the next "## " heading + awk -v tag="$TAG" ' + $1 == "##" && $2 == tag { found = 1; next } + found && /^## / { exit } + found { print } + ' CHANGELOG.md > notes.md + if ! grep -q '[^[:space:]]' notes.md; then + echo "CHANGELOG.md has no section for $TAG" + exit 1 + fi + cat notes.md + - name: Create the release or add missing files + run: | + if gh release view "$TAG" > /dev/null 2>&1; then + # A re-run keeps the existing notes and uploads only the + # files that the release does not hold yet + echo "Release $TAG exists already" + existing=$(gh release view "$TAG" --json assets --jq '.assets[].name') + for file in dist/*; do + name=$(basename "$file") + if printf '%s\n' "$existing" | grep -qxF "$name"; then + echo "Skip $name, which the release holds already" + else + gh release upload "$TAG" "$file" + fi + done + else + flags="" + case "$TAG" in *rc*) flags="--prerelease" ;; esac + gh release create "$TAG" dist/* \ + --title "$TAG" \ + --notes-file notes.md \ + --verify-tag \ + $flags + fi diff --git a/RELEASE.md b/RELEASE.md index 269fa8d9..9b7dfd3f 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -5,8 +5,7 @@ Follow the steps in this document to release a new version of Kaleido. ## Overview - Versions are determined automatically from git tags by `setuptools-git-versioning`. There is no hard-coded version string to update. Pushing a `v*` tag starts the `test-and-build` workflow, which builds and tests the package on each platform. That workflow publishes nothing. -- The `publish-pypi` workflow uploads the package to PyPI with trusted publishing (OIDC). A maintainer starts the workflow by hand, so no API token is necessary. -- Creating a GitHub release is done manually. +- The `publish-pypi` workflow uploads the package to PyPI with trusted publishing (OIDC), then creates the GitHub release. A maintainer starts the workflow by hand, so no API token is necessary. ## Release steps @@ -15,14 +14,15 @@ Follow the steps in this document to release a new version of Kaleido. 2. Update the changelog: - Review the items in `CHANGELOG.md` under the "Unreleased" header - Ensure all items follow this format: - - `- Description of change [[#XXXX](https://github.com/plotly/Kaleido/pull/XXXX)]` + - `- Description of change [[#XXXX](https://github.com/plotly/kaleido/pull/XXXX)]` - ...followed by `with thanks to @username for the contribution!` if the PR is from a community contributor - Add any missing items (PRs which were merged since the last release) - PRs which don't change the contents of the built package (e.g. changes to the README, etc.) and minor dependency upgrades don't need to be mentioned - - Add a header `## vX.Y.Z` above the unreleased items, under `## Unreleased` + - Add a header `## vX.Y.Z -- YYYY-MM-DD` above the unreleased items, under `## Unreleased` + - The `publish-pypi` workflow copies this section into the GitHub release notes. The second word of the header must be exactly the tag, or the workflow stops before it creates the release. - Commit and push the `CHANGELOG.md` updates - _Normally, the changelog is the only file that needs to be updated when making a release. The package version is determined automatically as explained in the overview above._ -3. Open a PR into `main`, wait for tests to pass, get approval, and then merge into `main`. +3. Open a PR into `main`, wait for tests to pass, get approval, and then merge into `main` 4. On your local machine, check out `main`, pull, and tag the release branch merge commit with the version number: ``` git checkout main @@ -34,15 +34,16 @@ Follow the steps in this document to release a new version of Kaleido. - The tag push starts `.github/workflows/test_and_build.yml` - The workflow builds the package on Linux, Windows, and macOS for each supported Python version, then runs the tests against the built wheel - If the workflow fails, read the failure before you continue. A flaky browser test does not block the release, but a build failure does. -6. Release on PyPI: +6. Release on PyPI and GitHub: - Open the Actions tab and select `publish-pypi` - Select "Run workflow", enter the tag (for example `vX.Y.Z`), and start the run - Open the run and approve the deployment under "Review deployments" - The `pypi` environment needs a review from the `plotly/libraries_admin` team. The job waits for that approval before GitHub issues the OIDC token, so an unapproved run never reaches PyPI. - - The workflow checks out the tag, builds the package, and confirms that the built version matches the tag. The upload uses `skip-existing`, so a second run of the same tag skips the files that PyPI holds already. -7. Release on GitHub: - - Go to https://github.com/plotly/Kaleido/releases and click "Draft a new release" - - Select the `vX.Y.Z` tag you created previously - - Copy and paste the relevant changelog section into the release notes + - The `pypi-publish` job checks out the tag, builds the package, and confirms that the built version matches the tag. The upload uses `skip-existing`, so a second run of the same tag skips the files that PyPI holds already. + - After the upload, the `github-release` job creates the GitHub release for the tag. The job uses the tag as the title and the matching `CHANGELOG.md` section as the notes. The job attaches the same `.whl` and `.tar.gz` files that went to PyPI. A tag that contains `rc` becomes a pre-release. + - If the release exists already, the job keeps the existing notes and uploads only the files that the release does not hold yet. Thus you can run the workflow again after a partial failure. +7. Confirm the release: + - Open https://github.com/plotly/kaleido/releases and make sure that the release has the correct notes and two attached files + - If the notes need a change, edit the release on GitHub. A second run of the workflow does not replace the notes. That's it! Make sure to visit https://pypi.org/project/kaleido to verify that the new package version is available.