Fix a deprecation msg typo in the ancient branch: "migrading"->"migrating" (#212)

This patch suggests the users to use `release/v1`.

Resolves #83

Dockerfile

@@ -1,4 +1,4 @@
-FROM python:3.7-slim
+FROM python:3.9-slim
 
 LABEL "maintainer" "Sviatoslav Sydorenko <wk+pypa@sydorenko.org.ua>"
 LABEL "repository" "https://github.com/pypa/gh-action-pypi-publish"
@@ -7,11 +7,14 @@ LABEL "homepage" "https://github.com/pypa/gh-action-pypi-publish"
 ENV PYTHONDONTWRITEBYTECODE 1
 ENV PYTHONUNBUFFERED 1
 
-RUN pip install --upgrade --no-cache-dir twine
+RUN \
+  pip install --upgrade --no-cache-dir pip-with-requires-python && \
+  pip install --upgrade --no-cache-dir --prefer-binary twine
 
 WORKDIR /app
 COPY LICENSE.md .
 COPY twine-upload.sh .
+COPY print-hash.py .
 
 RUN chmod +x twine-upload.sh
 ENTRYPOINT ["/app/twine-upload.sh"]

README.md

@@ -1,10 +1,20 @@
+[![SWUbanner]][SWUdocs]
+
 # PyPI publish GitHub Action
+
 This action allows you to upload your [Python distribution packages]
 in the `dist/` directory to PyPI.
 This text suggests a minimalistic usage overview. For more detailed
 walkthrough check out the [PyPA guide].
 
 
+## 🌇 `master` branch sunset ❗
+
+The `master` branch version has been sunset. Please, change the GitHub
+Action version you use from `master` to `release/v1` or use an exact
+tag, or a full Git commit SHA.
+
+
 ## Usage
 
 To use the action add the following step to your workflow file (e.g.
@@ -13,10 +23,10 @@ To use the action add the following step to your workflow file (e.g.
 
 ```yml
 - name: Publish a Python distribution to PyPI
-  uses: pypa/gh-action-pypi-publish@master
+  uses: pypa/gh-action-pypi-publish@release/v1
   with:
     user: __token__
-    password: ${{ secrets.pypi_password }}
+    password: ${{ secrets.PYPI_API_TOKEN }}
 ```
 
 > **Pro tip**: instead of using branch pointers, like `master`, pin versions of
@@ -38,16 +48,16 @@ So the full step would look like:
 ```yml
 - name: Publish package
   if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags')
-  uses: pypa/gh-action-pypi-publish@master
+  uses: pypa/gh-action-pypi-publish@release/v1
   with:
     user: __token__
-    password: ${{ secrets.pypi_password }}
+    password: ${{ secrets.PYPI_API_TOKEN }}
 ```
 
 The example above uses the new [API token][PyPI API token] feature of
 PyPI, which is recommended to restrict the access the action has.
 
-The secret used in `${{ secrets.pypi_password }}` needs to be created on the
+The secret used in `${{ secrets.PYPI_API_TOKEN }}` needs to be created on the
 settings page of your project on GitHub. See [Creating & using secrets].
 
 
@@ -57,6 +67,28 @@ This GitHub Action [has nothing to do with _building package
 distributions_]. Users are responsible for preparing dists for upload
 by putting them into the `dist/` folder prior to running this Action.
 
+> **IMPORTANT**: Since this GitHub Action is docker-based, it can only
+> be used from within GNU/Linux based jobs in GitHub Actions CI/CD
+> workflows. This is by design and is unlikely to change due to a number
+> of considerations we rely on.
+>
+> This should not stop one from publishing platform-specific
+> distribution packages, though. It is strongly advised to separate jobs
+> for building the OS-specific wheels from the publish job. This allows
+> one to (1) test exactly the same artifacts that are about to be
+> uploaded to PyPI, (2) prevent parallel unsynchronized jobs from
+> publishing only part of the dists asynchronously (in case when part of
+> the jobs fail and others succeed ending up with an incomplete release
+> on PyPI) and (3) make an atomic upload to PyPI (when part of the dists
+> appear on PyPI, installers like pip will use that version for the
+> dependency resolution but this may cause some environments to use
+> sdists while the wheel for their runtime is not yet available).
+>
+> To implement this sort of orchestration, please use
+> `actions/upload-artifact` and `actions/download-artifact` actions for
+> sharing the built dists across stages and jobs. Then, use the `needs`
+> setting to order the build, test and publish stages.
+
 
 ## Advanced release management
 
@@ -78,10 +110,10 @@ You'll need to create another token for a separate host and then
 The action invocation in this case would look like:
 ```yml
 - name: Publish package to TestPyPI
-  uses: pypa/gh-action-pypi-publish@master
+  uses: pypa/gh-action-pypi-publish@release/v1
   with:
     user: __token__
-    password: ${{ secrets.test_pypi_password }}
+    password: ${{ secrets.TEST_PYPI_API_TOKEN }}
     repository_url: https://test.pypi.org/legacy/
 ```
 
@@ -93,10 +125,10 @@ would now look like:
 
 ```yml
 - name: Publish package to PyPI
-  uses: pypa/gh-action-pypi-publish@master
+  uses: pypa/gh-action-pypi-publish@release/v1
   with:
     user: __token__
-    password: ${{ secrets.pypi_password }}
+    password: ${{ secrets.PYPI_API_TOKEN }}
     packages_dir: custom-dir/
 ```
 
@@ -111,6 +143,44 @@ check with:
      verify_metadata: false
 ```
 
+### Tolerating release package file duplicates
+
+Sometimes, when you publish releases from multiple places, your workflow
+may hit race conditions. For example, when publishing from multiple CIs
+or even having workflows with the same steps triggered within GitHub
+Actions CI/CD for different events concerning the same high-level act.
+
+To facilitate this use-case, you may use `skip_existing` (disabled by
+default) setting as follows:
+
+```yml
+   with:
+     skip_existing: true
+```
+
+> **Pro tip**: try to avoid enabling this setting where possible. If you
+have steps for publishing to both PyPI and TestPyPI, consider only using
+it for the latter, having the former fail loudly on duplicates.
+
+### For Debugging
+
+Sometimes, `twine upload` can fail and to debug use the `verbose` setting as follows:
+
+```yml
+   with:
+     verbose: true
+```
+
+### Showing hash values of files to be uploaded
+
+You may want to verify whether the files on PyPI were automatically uploaded by CI script.
+It will show SHA256, MD5, BLAKE2-256 values of files to be uploaded.
+
+```yml
+  with:
+    print_hash: true
+```
+
 ## License
 
 The Dockerfile and associated scripts and documentation in this project
@@ -126,3 +196,7 @@ https://packaging.python.org/guides/publishing-package-distribution-releases-usi
 [PyPI API token]: https://pypi.org/help/#apitoken
 [Python distribution packages]:
 https://packaging.python.org/glossary/#term-distribution-package
+[SWUbanner]:
+https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg
+[SWUdocs]:
+https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md

action.yml

@@ -4,22 +4,188 @@ description: Upload Python distribution packages to PyPI
 inputs:
   user:
     description: PyPI user
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
     required: false
     default: __token__
   password:
     description: Password for your PyPI user or an access token
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
     required: true
   repository_url:
     description: The repository URL to use
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
     required: false
   packages_dir:
     description: The target directory for distribution
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
     required: false
     default: dist
   verify_metadata:
     description: Check metadata before uploading
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
     required: false
     default: true
+  skip_existing:
+    description: >-
+      Do not fail if a Python package distribution
+      exists in the target package index
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
+    required: false
+    default: false
+  verbose:
+    description: Show verbose output.
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
+    required: false
+    default: false
+  print_hash:
+    description: Show hash values of files to be uploaded
+    deprecationMessage: >
+      UNSUPPORTED GITHUB ACTION VERSION
+
+
+      You are using `pypa/gh-action-pypi-publish@master`.
+      The `master` branch of this project has been sunset and will not
+      receive any updates, not even security bug fixes. Please, make
+      sure to use a supported version. If you want to pin to v1 major
+      version, use `pypa/gh-action-pypi-publish@release/v1`. If you
+      feel adventurous, you may opt to use use
+      `pypa/gh-action-pypi-publish@unstable/v1` instead. A more
+      general recommendation is to pin to exact tags or commit SHAs.
+
+
+      Please also consider migrating your setup to use secretless publishing:
+      https://github.com/marketplace/actions/pypi-publish#trusted-publishing
+
+
+      https://stand-with-ukraine.pp.ua
+    required: false
+    default: false
 branding:
   color: yellow
   icon: upload-cloud
@@ -32,3 +198,6 @@ runs:
   - ${{ inputs.repository_url }}
   - ${{ inputs.packages_dir }}
   - ${{ inputs.verify_metadata }}
+  - ${{ inputs.skip_existing }}
+  - ${{ inputs.verbose }}
+  - ${{ inputs.print_hash }}

print-hash.py

@@ -0,0 +1,26 @@
+import hashlib
+import pathlib
+import sys
+
+packages_dir = pathlib.Path(sys.argv[1]).resolve().absolute()
+
+print("Showing hash values of files to be uploaded:")
+
+for file_object in packages_dir.iterdir():
+    sha256 = hashlib.sha256()
+    md5 = hashlib.md5()
+    blake2_256 = hashlib.blake2b(digest_size=256 // 8)
+
+    print(file_object)
+    print("")
+
+    content = file_object.read_bytes()
+
+    sha256.update(content)
+    md5.update(content)
+    blake2_256.update(content)
+
+    print(f"SHA256: {sha256.hexdigest()}")
+    print(f"MD5: {md5.hexdigest()}")
+    print(f"BLAKE2-256: {blake2_256.hexdigest()}")
+    print("")

twine-upload.sh

@@ -2,13 +2,52 @@
 set -Eeuo pipefail
 
 
+echo \
+    '# UNSUPPORTED GITHUB ACTION VERSION' \
+    '\n\n' \
+    You are using `pypa/gh-action-pypi-publish@master`. \
+    The `master` branch of this project has been sunset and will not \
+    receive any updates, not even security bug fixes. Please, make \
+    sure to use a supported version. If you want to pin to v1 major \
+    version, use `pypa/gh-action-pypi-publish@release/v1`. If you \
+    feel adventurous, you may opt to use use \
+    `pypa/gh-action-pypi-publish@unstable/v1` instead. A more \
+    general recommendation is to pin to exact tags or commit shas. \
+    '\n\n' \
+    '\n\n' \
+    '### Oh, and while you are here — #StandWithUkraine' \
+    '\n\n' \
+    '[![SWUbanner]][SWUdocs]' \
+    '\n\n' \
+    '[SWUbanner]:' \
+    'https://raw.githubusercontent.com/vshymanskyy/StandWithUkraine/main/banner-direct-single.svg' \
+    '\n\n' \
+    '[SWUdocs]:' \
+    'https://github.com/vshymanskyy/StandWithUkraine/blob/main/docs/README.md' \
+    >> "${GITHUB_STEP_SUMMARY}"
+echo \
+    ::warning file='# >>' PyPA publish to PyPI GHA'%3A' \
+    UNSUPPORTED GITHUB ACTION VERSION \
+    '<< ':: \
+    You are using '"pypa/gh-action-pypi-publish@master"'. \
+    The '"master"' branch of this project has been sunset and will not \
+    receive any updates, not even security bug fixes. Please, make \
+    sure to use a supported version. If you want to pin to v1 major \
+    version, use '"pypa/gh-action-pypi-publish@release/v1"'. If you \
+    feel adventurous, you may opt to use use \
+    '"pypa/gh-action-pypi-publish@unstable/v1"' instead. A more \
+    general recommendation is to pin to exact tags or commit shas.
+
+
 if [[
     "$INPUT_USER" == "__token__" &&
     ! "$INPUT_PASSWORD" =~ ^pypi-
   ]]
 then
-    >&2 echo \
-        [WARNING]: \
+    echo \
+        ::warning file='# >>' PyPA publish to PyPI GHA'%3A' \
+        POTENTIALLY INVALID TOKEN \
+        '<< ':: \
         It looks like you are trying to use an API token to \
         authenticate in the package index and your token value does \
         not start with '"pypi-"' as it typically should. This may \
@@ -16,24 +55,37 @@ then
         copied your token properly if such an error occurs.
 fi
 
-if [[
-    ! -d ${INPUT_PACKAGES_DIR%%/}/ ||
-    "`ls -l ${INPUT_PACKAGES_DIR%%/}/*.tar.gz ${INPUT_PACKAGES_DIR%%/}/*.whl`" == "total 0"
-  ]]
+if ( ! ls -A ${INPUT_PACKAGES_DIR%%/}/*.tar.gz &> /dev/null && \
+     ! ls -A ${INPUT_PACKAGES_DIR%%/}/*.whl &> /dev/null )
 then
-    >&2 echo \
-        [WARNING]: \
+    echo \
+        ::warning file='# >>' PyPA publish to PyPI GHA'%3A' \
+        MISSING DISTS \
+        '<< ':: \
         It looks like there are no Python distribution packages to \
-        publish in the directory '"${INPUT_PACKAGES_DIR%%/}/"'. Please verify that they \
-        are in place should you face this problem.
+        publish in the directory "'${INPUT_PACKAGES_DIR%%/}/'". \
+        Please verify that they are in place should you face this \
+        problem.
 fi
 
 if [[ ${INPUT_VERIFY_METADATA,,} != "false" ]] ; then
     twine check ${INPUT_PACKAGES_DIR%%/}/*
 fi
 
+TWINE_EXTRA_ARGS=
+if [[ ${INPUT_SKIP_EXISTING,,} != "false" ]] ; then
+    TWINE_EXTRA_ARGS=--skip-existing
+fi
+
+if [[ ${INPUT_VERBOSE,,} != "false" ]] ; then
+    TWINE_EXTRA_ARGS="--verbose $TWINE_EXTRA_ARGS"
+fi
+
+if [[ ${INPUT_PRINT_HASH,,} != "false" || ${INPUT_VERBOSE,,} != "false" ]] ; then
+    python /app/print-hash.py ${INPUT_PACKAGES_DIR%%/}
+fi
 
 TWINE_USERNAME="$INPUT_USER" \
 TWINE_PASSWORD="$INPUT_PASSWORD" \
 TWINE_REPOSITORY_URL="$INPUT_REPOSITORY_URL" \
-  exec twine upload ${INPUT_PACKAGES_DIR%%/}/*
+  exec twine upload ${TWINE_EXTRA_ARGS} ${INPUT_PACKAGES_DIR%%/}/*