This PR adds a GitHub Actions workflow for publishing our upip package to PyPi. Itresolves#58.

Overview

I was inspired to create this by this article:https://simonwillison.net/2021/Nov/4/publish-open-source-python-library/, even though I now saw, that GitHub offers a workflow template for this too, using an action from its Actions Marketplace.

Instead of using a hardcoded version number during the build, setup.py now uses setuptools-scm to derive a useful/relevant version from git metadata (tags/commits).

The below is documentation mainly for once the PR has been merged, and for how to then test it and later release 1.0.0.

Setup

The workflow in this PR will require setting up 2 repository secrets (Settings -> Secrets -> Actions secrets -> New repository secret), namelyTEST_PYPI_API_TOKEN andPYPI_API_TOKEN (for TestPyPi and real PyPI respectively). These tokens can be generated in TestPyPI and real PyPI as follows:

• Log in
• Going to Account Settings -> API tokens
• Selecting "Add API token"
• Entering a token name, e.g. "publish-py-esp32-ulp"
• Selecting the right project
• And selecting "Add token"
• Copy the resulting token, which should be a long string starting withpypi-

Once you have the tokens for both TestPyPI and real PyPI, add them as repository secret to the Github repo.

Testing

To test this PR, it sadly needs to be merged to master (or a "dummy" publish.yml must be committed to master), otherwise Github does make this workflow available in the user interface. However, merging to master should be safe, as this workflow is only triggered when creating a release (which is a deliberate step) or by manually triggering the workflow.

Once merged to master, it can be tested by either triggering the workflow manually (a good first step), or by creating a new Release with Github.

• NOTE: Since PyPI does not allow reusing version numbers, it might be best to try the first release with a version number lower than 1.0.0, e.g. 0.0.1 and then deleting that version again once 1.0.0 is released (or just before).
• It might also be good to not configure the livePYPI_API_TOKEN secret initially, to prevent accidentally publishing test releases to the live PyPI.
• When manually triggering the workflow, and thus no tag is (yet) added to the repo, the version number of the package will be derived by setuptools-scm as0.1-devX whereX is the number of commits since the last tag (in our case, since the beginning of history, since we have no tags yet)

Test-before-publish

The article that inspired me to create this publishing workflow suggested to run the automated tests again as part of the publishing workflow to ensure no untested code is published. I like that idea.

However, I could not find a good way to do that without duplicating the test steps from the existing workflow into the new publish workflow. I tried many ways (seethe ideas I tried) and eventually decided to leave this out. Github Actions sadly does not provide good enough ways to reuse workflows or to make workflows dependent on each other.

I ended up deciding that simple is better and that publishing is a deliberate act on our part anyway (creating a Release with Github) so we can choose to release only when we know all tests pass.

Happy to get feedback on this.