diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
deleted file mode 100644
index c09c167..0000000
--- a/.github/workflows/release.yml
+++ /dev/null
@@ -1,46 +0,0 @@
-name: Release
-
-permissions:
-  contents: write
-  id-token: write
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-
-jobs:
-  build-and-publish:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@v7
-
-    - name: Set up Python
-      uses: actions/setup-python@v6
-      with:
-        python-version: '3.13'
-
-    - name: Install build dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build twine
-
-    - name: Build package
-      run: python -m build
-
-    - name: Check package
-      run: twine check dist/*
-
-    - name: Publish to PyPI
-      if: startsWith(github.ref, 'refs/tags/')
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        skip-existing: true
-
-    - name: Create GitHub Release
-      if: startsWith(github.ref, 'refs/tags/')
-      uses: softprops/action-gh-release@v3
-      with:
-        files: dist/*
-        generate_release_notes: true
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index ebc5424..129de76 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -130,6 +130,32 @@ pytest --cov=purl2src
 pytest tests/test_specific.py
 ```
 
+## Releasing
+
+Publishing to PyPI runs from `.github/workflows/python-publish.yml`, which triggers when a
+GitHub release is published and authenticates with PyPI trusted publishing through the `pypi`
+environment.
+
+```bash
+# 1. Bump the version in pyproject.toml and src/purl2src/__init__.py, add a CHANGELOG entry, merge it
+# 2. Tag the release commit
+git tag -a vX.Y.Z -m "Release X.Y.Z"
+git push origin vX.Y.Z
+
+# 3. Publish the release, which starts the PyPI upload
+gh release create vX.Y.Z --title "X.Y.Z" --generate-notes
+```
+
+Release notes are generated by GitHub from the merged pull requests, so they do not need to be
+written by hand.
+
+Step 3 has to be a real user action. A release created by a workflow using `GITHUB_TOKEN` does
+not raise the `release: published` event, so the publish workflow would never start.
+
+Confirm the upload with the version-specific endpoint, `https://pypi.org/pypi/purl2src/X.Y.Z/json`.
+The aggregate `https://pypi.org/pypi/purl2src/json` is cached and can lag a few minutes behind,
+which looks like a failed upload when it is not.
+
 ## Community
 
 You can chat with the community on: