From b54687a45c67898a8b30b6a2d7079d3504021e0b Mon Sep 17 00:00:00 2001
From: Oscar V <oscarvalenzuelab@users.noreply.github.com>
Date: Fri, 24 Jul 2026 12:16:40 -0700
Subject: [PATCH] ci: remove redundant, broken release.yml publish workflow

release.yml fired on tag push and tried to publish to PyPI without the trusted
publisher config used by python-publish.yml, so it failed on every release.
Its Create GitHub Release step ran after the failing upload in the same job,
so a tag push produced no release either.

Dropping only the upload step would be worse: a release created by a workflow
using GITHUB_TOKEN does not raise release: published, so python-publish.yml
would not start and the tag would yield a release with nothing on PyPI.

Every release in this repo was published by a user creating the GitHub release
with python-publish.yml picking up the event, all user-authored with no attached
assets, so release.yml never produced one. That path is unchanged. CONTRIBUTING.md
now documents it, including why the release must be created by a user.

Matches the same cleanup in upmex and src2purl.
---
 .github/workflows/release.yml | 46 -----------------------------------
 CONTRIBUTING.md               | 26 ++++++++++++++++++++
 2 files changed, 26 insertions(+), 46 deletions(-)
 delete mode 100644 .github/workflows/release.yml

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: