diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index ef68845..a235d32 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -10,10 +10,13 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v2
+        uses: actions/checkout@692973e3d937129bcbf40652eb9f2f61becf3332 # v4
+        with:
+          fetch-depth: 0 # setuptools_scm needs full history and tags to resolve the version
+          fetch-tags: true
 
       - name: Set up Python
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@39cd14951b08e74b54015e9e001cdefcf80e669f # v5
         with:
           python-version: "3.10"
 
@@ -32,6 +35,6 @@ jobs:
 
       - name: Publish a Python distribution to PyPI
         if: startsWith(github.event.ref, 'refs/tags') || github.event_name == 'release'
-        uses: pypa/gh-action-pypi-publish@master
+        uses: pypa/gh-action-pypi-publish@cef221092ed1bacb1cc03d23a2d87d1d172e277b # v1.14.0
         with:
           password: ${{ secrets.PYPI_API_TOKEN }}
diff --git a/pypi_update_guide.md b/pypi_update_guide.md
index e46bd0c..f045c29 100644
--- a/pypi_update_guide.md
+++ b/pypi_update_guide.md
@@ -41,6 +41,13 @@ _Creating and deploying a new package version is easy_
      - input [version](#version) (ex: `1.12.0`)
      - Click `Create new tag: x.x.x`
 
+     > **Note:** The tag name becomes the published package version. It is resolved
+     > automatically from the Git tag by `setuptools_scm` (there is no version string
+     > to edit in the source), so enter the exact version, matching the existing tag
+     > format (e.g. `1.12.0`, no `v` prefix). Creating the tag together with the
+     > release here is fine — the workflow checks out the full history and tags, so
+     > the version always resolves correctly.
+
    - Target: main
 
    - Release title: `Release x.x.x` (ex: `Release 1.12.0`)
@@ -69,6 +76,13 @@ If the workflow fails, follow these steps:
 
 ### Version
 
+The package version is **derived automatically from the Git tag** by
+[`setuptools_scm`](https://github.com/pypa/setuptools-scm) — see `[tool.setuptools_scm]`
+and `dynamic = ["version"]` in `pyproject.toml`. There is no version string to edit in
+the source; the tag you create in Step 1 is what gets published to PyPI, so it must be a
+valid version. (If the tag cannot be resolved, the build falls back to a dev version like
+`0.1.dev1+g<sha>`, which PyPI rejects with a `400 Bad Request`.)
+
 We use [semantic versioning](https://packaging.python.org/guides/distributing-packages-using-setuptools/#semantic-versioning-preferred).  
 If you are adding a meaningful feature, bump the minor version.  
 If you are fixing a bug, bump the incremental version.