From d1a568682779b191a671f4bbbc0b00f7a3163c00 Mon Sep 17 00:00:00 2001
From: Ludovic Henry <git@ludovic.dev>
Date: Sun, 6 Sep 2026 16:15:05 +0200
Subject: [PATCH 1/4] html-to-markdown: add build-html-to-markdown.yml for
 riscv64 wheels

---
 .github/workflows/build-html-to-markdown.yml | 99 ++++++++++++++++++++
 1 file changed, 99 insertions(+)
 create mode 100644 .github/workflows/build-html-to-markdown.yml

diff --git a/.github/workflows/build-html-to-markdown.yml b/.github/workflows/build-html-to-markdown.yml
new file mode 100644
index 000000000..87eb15b02
--- /dev/null
+++ b/.github/workflows/build-html-to-markdown.yml
@@ -0,0 +1,99 @@
+# SPDX-FileCopyrightText: 2026 The RISE Project
+# SPDX-License-Identifier: MIT
+---
+# This workflow is based on the `python-wheels` job of
+# https://github.com/xberg-io/html-to-markdown/blob/v3.12.0/.github/workflows/publish.yaml
+name: Build html-to-markdown wheels (riscv64)
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'html-to-markdown version to build (git tag without the leading v, e.g. 3.12.0)'
+        required: true
+        default: '3.12.0'
+  pull_request:
+    paths:
+      - '.github/workflows/build-html-to-markdown.yml'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ inputs.version || '3.12.0' }}-${{ github.head_ref || github.run_id }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read  # to fetch code (actions/checkout)
+
+env:
+  # `inputs.version` is empty on pull_request events; default to 3.12.0 there.
+  HTML_TO_MARKDOWN_VERSION: ${{ inputs.version || '3.12.0' }}
+  MANYLINUX_RISCV64_IMAGE: quay.io/pypa/manylinux_2_39_riscv64
+
+jobs:
+  setup:
+    uses: $/.github/workflows/_setup.yml
+
+  build_wheels:
+    needs: [setup]
+    name: Build html-to-markdown ${{ inputs.version || '3.12.0' }} cp310-abi3-manylinux_riscv64
+    runs-on: ubuntu-24.04-riscv
+    timeout-minutes: 180
+    steps:
+      - name: Checkout html-to-markdown v${{ env.HTML_TO_MARKDOWN_VERSION }}
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
+        with:
+          repository: xberg-io/html-to-markdown
+          ref: v${{ env.HTML_TO_MARKDOWN_VERSION }}
+          persist-credentials: false
+
+      - name: Build wheels
+        uses: pypa/cibuildwheel@1828c10ab37f080699c7b81cea34097c684a7074  # v4.2.0
+        with:
+          package-dir: packages/python
+          output-dir: wheelhouse/
+        env:
+          # abi3-py310 is baked unconditionally into packages/python/pyproject.toml's
+          # [tool.maturin] features, so one wheel serves every interpreter below;
+          # there is no free-threaded build (pyo3 abi3 can't target Py_GIL_DISABLED,
+          # and upstream itself ships no cp314t wheel).
+          CIBW_BUILD: >-
+            cp310-manylinux_riscv64 cp311-manylinux_riscv64
+            cp312-manylinux_riscv64 cp313-manylinux_riscv64
+            cp314-manylinux_riscv64
+          CIBW_MANYLINUX_RISCV64_IMAGE: ${{ env.MANYLINUX_RISCV64_IMAGE }}
+          # html-to-markdown ships no [tool.cibuildwheel]; the Rust toolchain its
+          # maturin backend needs is installed in-container here, same as upstream's
+          # own cibw-before-build-linux (publish.yaml's python-wheels job).
+          CIBW_BEFORE_ALL_LINUX: >-
+            curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+          CIBW_ENVIRONMENT_LINUX: >-
+            PATH="$PATH:$HOME/.cargo/bin"
+          # Mirrors scripts/prepare_wheel.py, which upstream's own before-build also
+          # runs: it cargo-builds the standalone CLI binary and bundles it into
+          # html_to_markdown/bin and the wheel's .data/scripts before maturin builds
+          # the extension module.
+          CIBW_BEFORE_BUILD_LINUX: >-
+            pip install maturin uv &&
+            python scripts/prepare_wheel.py
+          CIBW_TEST_REQUIRES: pytest pytest-asyncio pytest-timeout
+          CIBW_TEST_SOURCES: >-
+            e2e/python/conftest.py e2e/python/pyproject.toml e2e/python/tests
+          CIBW_TEST_COMMAND: >-
+            python -c "import html_to_markdown._html_to_markdown as m;
+            assert m.__file__.endswith('.so'), m.__file__" &&
+            python -m pytest -v e2e/python/tests
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
+        with:
+          name: html-to-markdown-${{ env.HTML_TO_MARKDOWN_VERSION }}-cp310-abi3-manylinux_riscv64
+          path: wheelhouse/*.whl
+          if-no-files-found: error
+
+  publish:
+    name: Publish html-to-markdown ${{ inputs.version || '3.12.0' }}
+    needs: [setup, build_wheels]
+    permissions:
+      contents: write
+      pull-requests: write
+    uses: $/.github/workflows/_publish-wheel.yml
+    with:
+      artifact-pattern: html-to-markdown-${{ inputs.version || '3.12.0' }}-*-manylinux_riscv64

From 8cf0eedce44384144c8085923fa639c1760a897c Mon Sep 17 00:00:00 2001
From: Ludovic Henry <git@ludovic.dev>
Date: Sun, 6 Sep 2026 17:38:26 +0200
Subject: [PATCH 2/4] html-to-markdown: deselect two v3.12.0 test-file
 NameError failures

test_options_preprocessing_{aggressive,minimal} fail with
NameError: name 'PreprocessingPreset' is not defined on every architecture,
not just riscv64: the test module's top-level import list omits
PreprocessingPreset even though two tests use it and html_to_markdown's
public __init__.py exports it. Already fixed on upstream main, just not in
a tagged release yet.
---
 .github/workflows/build-html-to-markdown.yml | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/.github/workflows/build-html-to-markdown.yml b/.github/workflows/build-html-to-markdown.yml
index 87eb15b02..ef5da51eb 100644
--- a/.github/workflows/build-html-to-markdown.yml
+++ b/.github/workflows/build-html-to-markdown.yml
@@ -77,10 +77,17 @@ jobs:
           CIBW_TEST_REQUIRES: pytest pytest-asyncio pytest-timeout
           CIBW_TEST_SOURCES: >-
             e2e/python/conftest.py e2e/python/pyproject.toml e2e/python/tests
+          # test_options_preprocessing_{aggressive,minimal} raise
+          # NameError: name 'PreprocessingPreset' is not defined at v3.12.0: the
+          # test module's import line omits PreprocessingPreset even though it's
+          # used later in the file and is exported by html_to_markdown.__init__;
+          # upstream's main branch already carries the fixed import, just not yet
+          # in a tagged release. Fails identically on every architecture.
           CIBW_TEST_COMMAND: >-
             python -c "import html_to_markdown._html_to_markdown as m;
             assert m.__file__.endswith('.so'), m.__file__" &&
             python -m pytest -v e2e/python/tests
+            -k "not test_options_preprocessing_aggressive and not test_options_preprocessing_minimal"
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a  # v7.0.1
         with:

From f8ded575d8ebfa445c70b3c4f33179248e7d81e2 Mon Sep 17 00:00:00 2001
From: Ludovic Henry <git@ludovic.dev>
Date: Sun, 6 Sep 2026 17:39:47 +0200
Subject: [PATCH 3/4] skill: add gotcha 285 from the html-to-markdown port

Documents diagnosing a NameError in an e2e test as a broken test file
at the pinned tag (already fixed upstream, unreleased) rather than a
riscv64 or extension-export problem, and why -k over --deselect avoids
the rootdir-nodeid trap gotcha 283 already hit.
---
 .../references/gotchas-index.md               |  1 +
 .../gotchas/test-failures-and-flakes.md       | 35 +++++++++++++++++++
 2 files changed, 36 insertions(+)

diff --git a/skills/python-project-porting/references/gotchas-index.md b/skills/python-project-porting/references/gotchas-index.md
index 39d0b8bda..fa5905a7c 100644
--- a/skills/python-project-porting/references/gotchas-index.md
+++ b/skills/python-project-porting/references/gotchas-index.md
@@ -309,6 +309,7 @@ The porting gotchas (221 of them) live in [`references/gotchas/`](gotchas/), spl
 - **205** — A follow-up commit that fixes a broken `Upstream-Status:` line does not clear
 - **282** — A matplotlib `image_comparison` test failing only on riscv64 is a font-rendering
 - **283** — A `cp314t`-only `PicklingError` from a `multiprocessing.Process(target=<local
+- **285** — A `NameError` in an e2e test for a name the package genuinely exports is a
 
 ### Licensing & GPL sources — [`gotchas/licensing-and-gpl.md`](gotchas/licensing-and-gpl.md)
 
diff --git a/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md b/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md
index 5a14067c3..f412fbbdf 100644
--- a/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md
+++ b/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md
@@ -23,6 +23,7 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/test-failures-and-flak
 - **205** — A follow-up commit that fixes a broken `Upstream-Status:` line does not clear
 - **282** — A matplotlib `image_comparison` test failing only on riscv64 is a font-rendering
 - **283** — A `cp314t`-only `PicklingError` from a `multiprocessing.Process(target=<local
+- **285** — A `NameError` in an e2e test for a name the package genuinely exports is a
 
 ---
 
@@ -510,3 +511,37 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/test-failures-and-flak
       test that already requests `get_context("fork")` explicitly (unaffected by the
       default) or whose target is a module-level function/bound method (pickles fine
       under any start method).
+
+285. **A `NameError` in an e2e test for a name the package genuinely exports is a
+    broken test file at that pinned tag, not an arch or extension-export problem (the
+    html-to-markdown case).** `test_options_preprocessing_{aggressive,minimal}` failed
+    with `NameError: name 'PreprocessingPreset' is not defined` on riscv64, 2 of 283
+    tests, identically deterministic (not flaky). Reading `packages/python/html_to_markdown/__init__.py`
+    at `v3.12.0` showed `PreprocessingPreset` re-exported from the compiled extension in
+    both the `from ._html_to_markdown import (...)` block and `__all__` — the built
+    wheel genuinely provides it — while `e2e/python/tests/test_options.py`'s own
+    top-level `from html_to_markdown import (...)` line simply omits it, even though two
+    tests further down use it. Diffing the tagged test file against upstream's `main`
+    confirmed the import list there already includes `PreprocessingPreset`: the bug was
+    fixed after `v3.12.0` was cut, just not yet in a tagged release. A failure this
+    narrow (one name, two tests, everything else in the module green) that traces to a
+    plain unimported symbol is a strong prior for "test file bug at this tag," worth
+    checking against upstream's default branch before assuming a build or export defect.
+    - **Confirm both halves before treating it as a test bug**: grep the test file's
+      import list for the missing name (absent) *and* the package's `__init__.py`/`__all__`
+      for the same name (present) — only the *combination* proves it's the test, not the
+      export, that's wrong. If the extension itself didn't export the name, the fix would
+      be a real compatibility issue to raise upstream, not a test deselect.
+    - **Fix with `-k "not <name>"` per test, not a path-based `--deselect`** (gotcha
+      14/283): a plain name-based `-k` sidesteps the rootdir-relative-nodeid trap
+      entirely, which matters here too since `CIBW_TEST_SOURCES` stages
+      `e2e/python/{conftest.py,pyproject.toml,tests}` and the staged `pyproject.toml`'s
+      own `[tool.pytest.ini_options]` puts pytest's rootdir one level away from the
+      `e2e/python/tests` path the `-v`/`FAILED` output displays.
+    - **Deselect in the workflow, don't patch the test file.** The test file is
+      upstream's own generated e2e suite (`# This file is auto-generated by alef — DO
+      NOT EDIT`) and the bug is already fixed on `main`; patching
+      `patches/<pkg>/<version>/` to hand-fix a file upstream has already corrected
+      would just be reverted by the next version bump. A `CIBW_TEST_COMMAND` comment
+      citing the exact `NameError` and noting upstream's fix is unreleased documents the
+      divergence for whoever reviews or re-triggers the workflow later.

From 69a28bd83c20d8bf348b39802e434b7370b50749 Mon Sep 17 00:00:00 2001
From: Ludovic Henry <git@ludovic.dev>
Date: Sun, 6 Sep 2026 19:35:17 +0200
Subject: [PATCH 4/4] Revert "skill: add gotcha 285 from the html-to-markdown
 port"

This reverts commit f8ded575d8ebfa445c70b3c4f33179248e7d81e2.
---
 .../references/gotchas-index.md               |  1 -
 .../gotchas/test-failures-and-flakes.md       | 35 -------------------
 2 files changed, 36 deletions(-)

diff --git a/skills/python-project-porting/references/gotchas-index.md b/skills/python-project-porting/references/gotchas-index.md
index fa5905a7c..39d0b8bda 100644
--- a/skills/python-project-porting/references/gotchas-index.md
+++ b/skills/python-project-porting/references/gotchas-index.md
@@ -309,7 +309,6 @@ The porting gotchas (221 of them) live in [`references/gotchas/`](gotchas/), spl
 - **205** — A follow-up commit that fixes a broken `Upstream-Status:` line does not clear
 - **282** — A matplotlib `image_comparison` test failing only on riscv64 is a font-rendering
 - **283** — A `cp314t`-only `PicklingError` from a `multiprocessing.Process(target=<local
-- **285** — A `NameError` in an e2e test for a name the package genuinely exports is a
 
 ### Licensing & GPL sources — [`gotchas/licensing-and-gpl.md`](gotchas/licensing-and-gpl.md)
 
diff --git a/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md b/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md
index f412fbbdf..5a14067c3 100644
--- a/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md
+++ b/skills/python-project-porting/references/gotchas/test-failures-and-flakes.md
@@ -23,7 +23,6 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/test-failures-and-flak
 - **205** — A follow-up commit that fixes a broken `Upstream-Status:` line does not clear
 - **282** — A matplotlib `image_comparison` test failing only on riscv64 is a font-rendering
 - **283** — A `cp314t`-only `PicklingError` from a `multiprocessing.Process(target=<local
-- **285** — A `NameError` in an e2e test for a name the package genuinely exports is a
 
 ---
 
@@ -511,37 +510,3 @@ To pull up one entry: `grep -n '^N\. ' references/gotchas/test-failures-and-flak
       test that already requests `get_context("fork")` explicitly (unaffected by the
       default) or whose target is a module-level function/bound method (pickles fine
       under any start method).
-
-285. **A `NameError` in an e2e test for a name the package genuinely exports is a
-    broken test file at that pinned tag, not an arch or extension-export problem (the
-    html-to-markdown case).** `test_options_preprocessing_{aggressive,minimal}` failed
-    with `NameError: name 'PreprocessingPreset' is not defined` on riscv64, 2 of 283
-    tests, identically deterministic (not flaky). Reading `packages/python/html_to_markdown/__init__.py`
-    at `v3.12.0` showed `PreprocessingPreset` re-exported from the compiled extension in
-    both the `from ._html_to_markdown import (...)` block and `__all__` — the built
-    wheel genuinely provides it — while `e2e/python/tests/test_options.py`'s own
-    top-level `from html_to_markdown import (...)` line simply omits it, even though two
-    tests further down use it. Diffing the tagged test file against upstream's `main`
-    confirmed the import list there already includes `PreprocessingPreset`: the bug was
-    fixed after `v3.12.0` was cut, just not yet in a tagged release. A failure this
-    narrow (one name, two tests, everything else in the module green) that traces to a
-    plain unimported symbol is a strong prior for "test file bug at this tag," worth
-    checking against upstream's default branch before assuming a build or export defect.
-    - **Confirm both halves before treating it as a test bug**: grep the test file's
-      import list for the missing name (absent) *and* the package's `__init__.py`/`__all__`
-      for the same name (present) — only the *combination* proves it's the test, not the
-      export, that's wrong. If the extension itself didn't export the name, the fix would
-      be a real compatibility issue to raise upstream, not a test deselect.
-    - **Fix with `-k "not <name>"` per test, not a path-based `--deselect`** (gotcha
-      14/283): a plain name-based `-k` sidesteps the rootdir-relative-nodeid trap
-      entirely, which matters here too since `CIBW_TEST_SOURCES` stages
-      `e2e/python/{conftest.py,pyproject.toml,tests}` and the staged `pyproject.toml`'s
-      own `[tool.pytest.ini_options]` puts pytest's rootdir one level away from the
-      `e2e/python/tests` path the `-v`/`FAILED` output displays.
-    - **Deselect in the workflow, don't patch the test file.** The test file is
-      upstream's own generated e2e suite (`# This file is auto-generated by alef — DO
-      NOT EDIT`) and the bug is already fixed on `main`; patching
-      `patches/<pkg>/<version>/` to hand-fix a file upstream has already corrected
-      would just be reverted by the next version bump. A `CIBW_TEST_COMMAND` comment
-      citing the exact `NameError` and noting upstream's fix is unreleased documents the
-      divergence for whoever reviews or re-triggers the workflow later.