Enhance firmware release workflow even more

Author: zamkorus

.github/workflows/build-firmware.yml

@@ -8,8 +8,16 @@ on:
         description: "MicroPython git tag/branch to build from"
         type: string
         default: "v1.28.0"
-  push:
-    tags: ["v*.*.*"]
+  # Version tags come in through publish-stubs.yml, which calls this and only
+  # publishes if it passes. No `push: tags` trigger of its own -- that would
+  # build the firmware twice on every tag and cut the release job loose from
+  # the gate it is supposed to be.
+  workflow_call:
+    inputs:
+      micropython_ref:
+        description: "MicroPython git tag/branch to build from"
+        type: string
+        default: "v1.28.0"
 
 jobs:
   build:

.github/workflows/publish-stubs.yml

@@ -1,28 +1,52 @@
 # .github/workflows/publish-stubs.yml
-name: Publish stubs to PyPI
+#
+# Publishes the generated `alpaca-stubs` package to PyPI and anaconda.org.
+#
+# NOTE: PyPI matches the trusted publisher on THIS file's name.
+
+name: Publish stubs
 
 on:
   push:
     tags: ["v*.*.*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: publish-stubs-${{ github.ref }}
+  cancel-in-progress: false
 
 jobs:
+  firmware:
+    # Release gate. These used to fire on the same tag independently, so a
+    # firmware failure after the stubs had published burned that version on
+    # PyPI for good. Tags only: a pull request just dry-runs the stubs.
+    if: github.ref_type == 'tag'
+    uses: ./.github/workflows/build-firmware.yml
+    permissions:
+      contents: write # the firmware workflow attaches .uf2 files to the release
+
   publish:
+    needs: firmware
+    # always(), so a deliberately skipped firmware build on a pull request does
+    # not block the dry run, while a failed one still does.
+    if: always() && needs.firmware.result != 'failure' && needs.firmware.result != 'cancelled'
     runs-on: ubuntu-latest
     environment: pypi
     permissions:
-      id-token: write
+      id-token: write # mints the OIDC token for PyPI; without it, auth fails
       contents: read
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v5
-
-      - name: Generate stubs
-        run: uv run alpaca generate-stubs student
-
-      - name: Build
-        working-directory: .alpaca/stubs
-        run: uv build
+      - uses: actions/checkout@v5
 
-      - name: Publish to PyPI
-        working-directory: .alpaca/stubs
-        run: uv publish
+      - uses: PlohnenSoftware/PyPI-Anaconda-Publish@v2
+        with:
+          prepare: uv run alpaca generate-stubs student
+          project_dir: .alpaca/stubs
+          tag: ${{ github.ref_type == 'tag' && github.ref_name || '' }}
+          anaconda_owner: NB_TUDelft
+          anaconda_api_key: ${{ secrets.ANACONDA_API_KEY }}
+          dry_run: ${{ github.event_name == 'pull_request' }}

cli/generate_stubs.py

@@ -36,9 +36,25 @@ def generate_stubs_cmd(pico_name: Annotated[str, typer.Argument(help="Pico name
     (stubs_folder / file).unlink(True)
 
 
+  # This package deliberately ships no runtime dependencies. The one it would
+  # want, micropython-rp2-stubs, exists only on PyPI -- it is on no anaconda.org
+  # channel, and neither is its own dependency micropython-stdlib-stubs --  so
+  # declaring it would leave the conda package unsolvable. The isinstance(str)
+  # filter below drops `dependencies` anyway; this note is here so that stays a
+  # decision rather than an accident. Users who want stubs for the MicroPython
+  # builtins install them separately, as the README below explains.
   (stubs_folder / "README.md").write_text(
-    "Stubs for " +
-    (PROJECT_ROOT / 'README.md').read_text(encoding='utf-8')
+    "Stubs for "
+    + (PROJECT_ROOT / 'README.md').read_text(encoding='utf-8')
+    + "\n\n## MicroPython builtins\n\n"
+      "These stubs cover ALPACA itself. For `machine`, `rp2` and the rest of\n"
+      "the MicroPython standard library, install those stubs alongside:\n\n"
+      "```bash\n"
+      "pip install micropython-rp2-stubs\n"
+      "```\n\n"
+      "They are not published on any conda channel, so they are not declared\n"
+      "as a dependency here. Without them only the MicroPython builtins stay\n"
+      "unresolved in your editor; the ALPACA stubs themselves work either way.\n"
   )
 
   parent = toml.load(PROJECT_ROOT / "pyproject.toml")
@@ -60,6 +76,19 @@ def generate_stubs_cmd(pico_name: Annotated[str, typer.Argument(help="Pico name
       "setuptools": {
         "packages": packages,
         "package-data": dict.fromkeys(packages, ["*.pyi"])
+      },
+      # Read by PlohnenSoftware/PyPI-Anaconda-Publish, which renders the conda
+      # recipe from this file so the conda package cannot drift from the PyPI one.
+      "conda-recipe": {
+        # Only .pyi files, so a single noarch build serves every architecture
+        # and every Python the inherited requires-python allows.
+        "noarch": True,
+        "build-channels": ["conda-forge"],
+        "maintainers": ["NB-TUDelft"],
+        # Deliberately empty. A PEP 561 stub-only distribution ships no runtime
+        # module, so importing these packages is *meant* to fail -- listing them
+        # here would fail the conda test phase.
+        "test-imports": []
       }
     }
   }, (stubs_folder / "pyproject.toml").open("w+"))

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "alpaca"
-version = "0.2.1"
+version = "0.2.2"
 description = "Libraries for ALPACA 2.0 - NB2420 Electronic Instrumentation"
 readme = "README.md"
 requires-python = ">=3.14"