Add release instructions and CD automation (#235)

- Build the distribution package (wheel file) in CI
- Install from wheel file so that CI tests imitate users who install
xl2times from PyPI
- CD: when releases are published on GitHub, automatically upload to
PyPI
- Add release instruction to README

I'm merging this PR in so that I can test the publish-upon-release
action with Test-PyPI. If you have any comments, please leave them here,
and I'll resolve them in the next PR that swaps Test-PyPI for real PyPI.
Thanks!

.github/workflows/ci.yml

@@ -6,13 +6,17 @@ on:
     branches: [main]
   pull_request:
     branches: [main]
+  release:
+    types: [published]
 
   # Allows you to run this workflow manually from the Actions tab
   workflow_dispatch:
 
 jobs:
   CI:
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
 
     env:
       PY_VERSION: "3.11"
@@ -33,16 +37,23 @@ jobs:
         with:
           python-version: ${{ env.PY_VERSION }}
 
-      - name: Install tool and dependencies
+      - name: Build and install xl2times
         working-directory: xl2times
         run: |
           python -m venv .venv
           source .venv/bin/activate
-          python -m pip install --upgrade pip
-          python -m pip install -e .[dev]
+          pip install --upgrade pip build
+          pip install -e .[dev]
+          # Build xl2times
+          rm -rf dist || true
+          python -m build
+          # Install the built wheel file to imitiate users installing from PyPI:
+          pip uninstall --yes xl2times
+          pip install --find-links=dist xl2times
 
       - name: Check code formatting
         working-directory: xl2times
+        # Run this step after install so that pyright can find dependencies like pandas
         run: |
           source .venv/bin/activate
           pre-commit install
@@ -170,3 +181,12 @@ jobs:
         with:
           path: ~/.cache/xl2times
           key: ${{ runner.os }}-py-${{ env.PY_VERSION }}-${{ env.REF_demos-xlsx }}-${{ env.REF_tim }}-${{ env.CACHE_KEY }}
+
+      # ---------- Upload package to PyPI on release
+
+      - name: Publish to PyPI
+        if: github.event_name == 'release' && github.event.action == 'published'
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: xl2times/dist/

.pre-commit-config.yaml

@@ -1,10 +1,14 @@
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.3.0
+    rev: v4.5.0
     hooks:
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
+      - id: check-merge-conflict
+      - id: mixed-line-ending
+      - id: check-added-large-files
+        args: ["--maxkb=2000"]
 
   - repo: https://github.com/psf/black
     rev: 22.8.0

README.md

@@ -52,7 +52,6 @@ We recommend installing the tool in editable mode (`-e`) in a Python virtual env
 python3 -m venv .venv
 source .venv/bin/activate
 pip install -U pip
-pip install -r requirements.txt
 pip install -e .[dev]
 ```
 
@@ -132,14 +131,11 @@ VS Code will highlight the changes in the two files, which should correspond to
 
 ### Publishing the Tool
 
-To publish a new version of the tool on PyPI, update the version number in `pyproject.toml`, and then run:
-```bash
-python -m pip install --upgrade build
-python -m pip install --upgrade twine
-rm -rf dist
-python -m build
-python -m twine upload dist/*
-```
+Follow these steps to release a new version of `xl2times` and publish it on PyPI:
+- [ ] Bump the version number in `pyproject.toml` and `xl2times/__init__.py` (use [Semantic Versioning](https://semver.org/))
+- [ ] Open a PR with this change titled "Release vX.Y.Z"
+- [ ] When the PR is merged, create a [new release](https://github.com/etsap-TIMES/xl2times/releases/new) titled "vX.Y.Z". Select "Create a new tag: on publish" and click "Generate release notes" to generate the notes automatically.
+- [ ] Click "Publish release" to publish the release on GitHub. A GitHub Actions workflow will automatically upload the distribution to PyPI.
 
 ## Contributing
 

pyproject.toml

@@ -2,12 +2,13 @@
 requires = ["setuptools>=61.0.0", "wheel"]
 build-backend = "setuptools.build_meta"
 
-[tool.setuptools]
-packages = ["xl2times"]
+[tool.setuptools.packages.find]
+where = [""]
+include = ["xl2times", "xl2times.*"]
 
 [project]
 name = "xl2times"
-version = "0.1.0"
+version = "0.1.0-alpha.2"
 authors = [
     { name="Sam Webster", email="[email protected]" },
     { name="Tom Minka", email="[email protected]" },