Build + publish on Github Actions

.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+# ref: https://help.github.com/en/actions/language-and-framework-guides/using-python-with-github-actions#publishing-to-package-registries
+
+name: Publish Package
+
+on:
+  # publish from the Releases page:
+  release:
+    types: [published]
+
+  # publish from the Actions page:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version'
+        required: true
+
+jobs:
+  publish:
+    name: Publish Package
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v3
+
+    - name: Create given tag
+      # because we use setuptools_scm, the tag needs to exist before running `build`
+      # this is a bit redundant because softprops/action-gh-release will recreate the
+      # same tag, on github
+      if: github.event.inputs.version
+      run: |
+        git tag -f "${{ github.event.inputs.version }}"
+
+    - uses: actions/setup-python@v3
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install build
+
+    - name: Build
+      run: python -m build
+
+    - name: Publish to Github
+      uses: softprops/action-gh-release@v1
+      with:
+        files: 'dist/*'
+        fail_on_unmatched_files: true
+        tag_name: ${{ github.event.inputs.version }} # in the workflow_dispatch case, make a new tag from the given input; in the published release case, this will be empty and will fall back to updating that release.
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: __token__
+        password: ${{ secrets.PYPI_TOKEN }}

CONTRIBUTING.md

@@ -33,24 +33,33 @@ doas rcctl resetart radicale
 
 ## Publishing
 
-(this is mostly a note to self)
+To publish a new version, go to https://github.com/kousu/radicale-bsdauth/releases/new and fill in a new tag `vX.Y.Zrc0` and click Publish.
+It will automatically be built and published (via [.github/workflows/publish.yml](.github/workflows/publish.yml)) to https://github.com/kousu/radicale-bsdauth/releases and https://pypi.org/project/radicale-bsdauth/.
 
-To publish a new version, use
+You should make sure to tag it with the 'rc' (release candidate) part initially,
+to make sure not to disrupt any users. Before fully publishingly, you can test the built version with
 
 ```
-git tag vX.Y.Zrc0
-python -m build
+pip install --upgrade --pre radicale-bsdauth
 ```
 
-The 'rc' part makes sure it won't accidentally be used before it's ready: you *cannot replace files on https://pypi.org* so be careful with your tagging.
+As you find and squash the final bugs, you can create a series of Releases tagged with 'rc1', 'rc2', etc
+and test each in turn.
+
+When you have a version that works, re-submit it (without making any more commits!) as `vX.Y.Z`; at that point,
+people running `pip install --upgrade radicale-bsdauth` will get the new version.
+
+
+You do not necessarily need to _create_ a tag through the Releases page: you can use `git tag` locally
+to manage your tags, and then `git push --tags` to upload them to Github, and then pick them out from the
+liist on the New Release page.
 
 
-When you are happy with it, do a final real tag:
+### Debugging
+
+If you need to debug the release process, you can emulate it locally with
 
 ```
 git tag vX.Y.Zrc0
-git push --tags
+python -m build
 ```
-
-
-( TODO:  upload to pypi )