ci: harden workflow gates release checks and version consistency

Author: skhe

.github/workflows/build-wheels.yml

@@ -62,11 +62,11 @@ jobs:
           /tmp/test_venv/bin/python -c "import dmPython; print('dmPython version:', dmPython.version)"
 
       - name: Build extension for optional integration tests
-        if: ${{ secrets.DM_TEST_HOST != '' && secrets.DM_TEST_PORT != '' && secrets.DM_TEST_USER != '' && secrets.DM_TEST_PASSWORD != '' }}
+        if: ${{ matrix.python-version == '3.10' && secrets.DM_TEST_HOST != '' && secrets.DM_TEST_PORT != '' && secrets.DM_TEST_USER != '' && secrets.DM_TEST_PASSWORD != '' }}
         run: DMPYTHON_SKIP_GO_BUILD=1 python setup.py build_ext --inplace
 
       - name: Run optional DM integration tests
-        if: ${{ secrets.DM_TEST_HOST != '' && secrets.DM_TEST_PORT != '' && secrets.DM_TEST_USER != '' && secrets.DM_TEST_PASSWORD != '' }}
+        if: ${{ matrix.python-version == '3.10' && secrets.DM_TEST_HOST != '' && secrets.DM_TEST_PORT != '' && secrets.DM_TEST_USER != '' && secrets.DM_TEST_PASSWORD != '' }}
         env:
           DYLD_LIBRARY_PATH: ${{ github.workspace }}/dpi_bridge
           DM_TEST_HOST: ${{ secrets.DM_TEST_HOST }}
@@ -83,15 +83,16 @@ jobs:
           python -m pytest -q -m requires_dm tests --cov=. --cov-report=term-missing --cov-report=xml:coverage.xml
 
       - name: Upload optional integration coverage
-        if: ${{ secrets.DM_TEST_HOST != '' && secrets.DM_TEST_PORT != '' && secrets.DM_TEST_USER != '' && secrets.DM_TEST_PASSWORD != '' }}
+        if: ${{ matrix.python-version == '3.10' && secrets.DM_TEST_HOST != '' && secrets.DM_TEST_PORT != '' && secrets.DM_TEST_USER != '' && secrets.DM_TEST_PASSWORD != '' }}
         uses: actions/upload-artifact@v4
         with:
-          name: coverage-wheel-py${{ matrix.python-version }}
+          name: coverage-wheel-baseline-py${{ matrix.python-version }}
           path: coverage.xml
 
       - name: Skip optional integration tests (missing DM secrets)
-        if: ${{ secrets.DM_TEST_HOST == '' || secrets.DM_TEST_PORT == '' || secrets.DM_TEST_USER == '' || secrets.DM_TEST_PASSWORD == '' }}
-        run: echo "Skipping requires_dm tests: DM_TEST_HOST/PORT/USER/PASSWORD secrets not fully configured."
+        if: ${{ matrix.python-version == '3.10' && (secrets.DM_TEST_HOST == '' || secrets.DM_TEST_PORT == '' || secrets.DM_TEST_USER == '' || secrets.DM_TEST_PASSWORD == '') }}
+        run: |
+          echo "::notice::SKIP_DM_INTEGRATION: DM_TEST_HOST/PORT/USER/PASSWORD secrets are not fully configured."
 
       - uses: actions/upload-artifact@v4
         with:
@@ -114,15 +115,103 @@ jobs:
           pattern: wheel-*
           merge-multiple: true
 
+      - name: Validate wheel set and generate release metadata
+        env:
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import glob
+          import json
+          import os
+          import re
+          import subprocess
+          import sys
+
+          wheels = sorted(glob.glob("dist_fixed/*.whl"))
+          if len(wheels) != 5:
+              print(f"Expected 5 wheels, got {len(wheels)}")
+              print("\n".join(wheels))
+              sys.exit(1)
+
+          expected_tags = {"cp39-cp39", "cp310-cp310", "cp311-cp311", "cp312-cp312", "cp313-cp313"}
+          found_tags = set()
+          for wheel in wheels:
+              name = os.path.basename(wheel)
+              if "arm64.whl" not in name:
+                  print(f"Non-arm64 wheel found: {name}")
+                  sys.exit(1)
+              match = re.search(r"-(cp\d{2,3}-cp\d{2,3})-macosx_.*_arm64\.whl$", name)
+              if not match:
+                  print(f"Unrecognized wheel naming pattern: {name}")
+                  sys.exit(1)
+              found_tags.add(match.group(1))
+          if found_tags != expected_tags:
+              print(f"Wheel tag mismatch. expected={sorted(expected_tags)} found={sorted(found_tags)}")
+              sys.exit(1)
+
+          with open("dist_fixed/build-metadata.json", "w", encoding="utf-8") as f:
+              json.dump(
+                  {
+                      "tag": os.environ["TAG_NAME"],
+                      "commit": os.environ.get("GITHUB_SHA", ""),
+                      "workflow": os.environ.get("GITHUB_WORKFLOW", ""),
+                      "run_id": os.environ.get("GITHUB_RUN_ID", ""),
+                      "run_attempt": os.environ.get("GITHUB_RUN_ATTEMPT", ""),
+                      "wheels": [os.path.basename(w) for w in wheels],
+                  },
+                  f,
+                  ensure_ascii=False,
+                  indent=2,
+              )
+
+          subprocess.check_call("shasum -a 256 dist_fixed/*.whl > dist_fixed/checksums.txt", shell=True)
+          PY
+
       - name: Upsert GitHub Release
         env:
           GH_TOKEN: ${{ github.token }}
           TAG_NAME: ${{ github.ref_name }}
         run: |
           if gh release view "$TAG_NAME" >/dev/null 2>&1; then
             echo "Release $TAG_NAME already exists, uploading artifacts with --clobber"
-            gh release upload "$TAG_NAME" dist_fixed/*.whl --clobber
+            gh release upload "$TAG_NAME" dist_fixed/*.whl dist_fixed/checksums.txt dist_fixed/build-metadata.json --clobber
           else
             echo "Creating release $TAG_NAME"
-            gh release create "$TAG_NAME" --generate-notes dist_fixed/*.whl
+            gh release create "$TAG_NAME" --generate-notes dist_fixed/*.whl dist_fixed/checksums.txt dist_fixed/build-metadata.json
           fi
+
+      - name: Verify release assets completeness
+        env:
+          GH_TOKEN: ${{ github.token }}
+          TAG_NAME: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import json
+          import os
+          import re
+          import subprocess
+          import sys
+
+          tag = os.environ["TAG_NAME"]
+          raw = subprocess.check_output(
+              ["gh", "release", "view", tag, "--json", "assets"],
+              text=True,
+          )
+          assets = [a["name"] for a in json.loads(raw)["assets"]]
+          expected_tags = {"cp39-cp39", "cp310-cp310", "cp311-cp311", "cp312-cp312", "cp313-cp313"}
+          found_tags = set()
+          for name in assets:
+              m = re.search(r"-(cp\d{2,3}-cp\d{2,3})-macosx_.*_arm64\.whl$", name)
+              if m:
+                  found_tags.add(m.group(1))
+          missing_tags = sorted(expected_tags - found_tags)
+          required_files = {"checksums.txt", "build-metadata.json"}
+          missing_files = sorted(f for f in required_files if f not in assets)
+          if missing_tags or missing_files:
+              print("Release assets are incomplete.")
+              print(f"missing wheel tags: {missing_tags}")
+              print(f"missing files: {missing_files}")
+              print(f"assets: {assets}")
+              sys.exit(1)
+          print("Release assets verified:", assets)
+          PY

.github/workflows/integration-tests.yml

@@ -58,18 +58,21 @@ jobs:
         run: |
           python -m pip install pytest pytest-timeout pytest-cov
           python setup.py build_ext --inplace
-          python -m pytest -q tests/integration -m "p0_stability or p1_contract" --cov=. --cov-report=term-missing --cov-report=xml:coverage.xml
+          python -m pytest -q tests/integration -m "p0_stability or p1_contract" --junitxml=pytest-pr.xml --cov=. --cov-report=term-missing --cov-report=xml:coverage.xml
 
       - name: Upload coverage report (PR)
         if: steps.dm_ready.outputs.available == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: coverage-pr
-          path: coverage.xml
+          path: |
+            coverage.xml
+            pytest-pr.xml
 
       - name: Skip lightweight integration tests
         if: steps.dm_ready.outputs.available != 'true'
-        run: echo "Skipping PR integration tests: DM secrets are not configured."
+        run: |
+          echo "::notice::SKIP_DM_INTEGRATION: PR integration tests are skipped because DM secrets are not configured."
 
   full-regression:
     if: github.event_name == 'workflow_dispatch' || github.event_name == 'schedule'
@@ -125,15 +128,40 @@ jobs:
         run: |
           python -m pip install pytest pytest-timeout pytest-cov
           python setup.py build_ext --inplace
-          python -m pytest -q tests/integration -m "p0_stability or p1_contract or p2_scale" --cov=. --cov-report=term-missing --cov-report=xml:coverage.xml
+          start_ts=$(date +%s)
+          python -m pytest -q tests/integration -m "p0_stability or p1_contract or p2_scale" --junitxml=pytest-full.xml --cov=. --cov-report=term-missing --cov-report=xml:coverage.xml
+          end_ts=$(date +%s)
+          duration=$((end_ts - start_ts))
+          python - <<PY
+          import json
+          import xml.etree.ElementTree as ET
+
+          root = ET.parse("pytest-full.xml").getroot()
+          attrs = root.attrib
+          trend = {
+              "tests": int(float(attrs.get("tests", "0"))),
+              "failures": int(float(attrs.get("failures", "0"))),
+              "errors": int(float(attrs.get("errors", "0"))),
+              "skipped": int(float(attrs.get("skipped", "0"))),
+              "pytest_reported_seconds": float(attrs.get("time", "0")),
+              "wall_clock_seconds": int(${duration}),
+          }
+          with open("trend-full-regression.json", "w", encoding="utf-8") as f:
+              json.dump(trend, f, indent=2, ensure_ascii=False)
+          print(trend)
+          PY
 
       - name: Upload coverage report (full)
         if: steps.dm_ready.outputs.available == 'true'
         uses: actions/upload-artifact@v4
         with:
           name: coverage-full
-          path: coverage.xml
+          path: |
+            coverage.xml
+            pytest-full.xml
+            trend-full-regression.json
 
       - name: Skip full integration tests
         if: steps.dm_ready.outputs.available != 'true'
-        run: echo "Skipping full integration tests: DM secrets are not configured."
+        run: |
+          echo "::notice::SKIP_DM_INTEGRATION: Full regression is skipped because DM secrets are not configured."

.github/workflows/workflow-lint.yml

@@ -0,0 +1,42 @@
+name: Workflow Lint
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install lint dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install pyyaml build twine
+
+      - name: Parse workflow YAML files
+        run: |
+          python scripts/check_workflow_yaml.py
+
+      - name: Run actionlint
+        uses: rhysd/actionlint@v1
+
+      - name: Check version consistency
+        run: |
+          python scripts/check_version_consistency.py
+
+      - name: Check third-party patch consistency
+        run: |
+          python scripts/check_third_party_patch.py
+
+      - name: Packaging metadata check (sdist)
+        run: |
+          python -m build --sdist --outdir /tmp/dist_meta
+          python -m twine check /tmp/dist_meta/*

Makefile

@@ -1,4 +1,4 @@
-.PHONY: go-bridge wheel wheel-delocated universal2 clean test-install dpi-headers-secret
+.PHONY: go-bridge wheel wheel-delocated universal2 clean test-install dpi-headers-secret release-preflight
 
 # Go bridge library
 GO_BRIDGE_DIR = dpi_bridge
@@ -47,6 +47,10 @@ test-install:
 	@echo "Test passed! Cleaning up..."
 	rm -rf /tmp/dmpython_test_venv
 
+# Release preflight checks (optional: make release-preflight TAG=v2.5.31)
+release-preflight:
+	./scripts/release_preflight.sh $(TAG)
+
 # Package DPI headers as base64 for GitHub Secret
 dpi-headers-secret:
 	@tar czf - -C dpi_include . | base64 | pbcopy

README.md

@@ -14,7 +14,7 @@ This is a community fork of the [official dmPython](https://github.com/DamengDB/
 Download a pre-built wheel from [GitHub Releases](https://github.com/skhe/dmPython/releases):
 
 ```bash
-pip install dmPython_macOS-2.5.30-cp312-cp312-macosx_14_0_arm64.whl
+pip install dmPython_macOS-2.5.31-cp312-cp312-macosx_14_0_arm64.whl
 ```
 
 ## Quick Start

docs/README_zh.md

@@ -25,7 +25,7 @@ dmPython 是达梦数据库（DM8）的原生 Python 驱动程序，遵循 [Pyth
 从 [GitHub Releases](https://github.com/skhe/dmPython/releases) 下载预编译 wheel：
 
 ```bash
-pip install dmPython_macOS-2.5.30-cp312-cp312-macosx_14_0_arm64.whl
+pip install dmPython_macOS-2.5.31-cp312-cp312-macosx_14_0_arm64.whl
 ```
 
 ## 快速开始

docs/release-checklist.md

@@ -0,0 +1,28 @@
+# Release Checklist
+
+## 1. Preflight
+- [ ] Run `./scripts/release_preflight.sh vX.Y.Z`
+- [ ] Confirm workflow lint and actionlint checks are green
+- [ ] Confirm version consistency (`pyproject.toml`, `setup.py`, `src/native/py_Dameng.h`, `dmPython.version`)
+- [ ] Confirm third-party patch checks pass (`scripts/check_third_party_patch.py`)
+
+## 2. Regression
+- [ ] Run `DYLD_LIBRARY_PATH=/Users/skhe/projects/dmPython/dpi_bridge python3 -m pytest -q -m requires_dm tests`
+- [ ] Confirm P0/P1/P2 integration markers are green
+- [ ] Confirm no `Segmentation fault` / no `139/-11` exits
+
+## 3. Tag & CI
+- [ ] Push release tag `vX.Y.Z`
+- [ ] Confirm `Build macOS wheels` workflow succeeds for all Python targets (`cp39/cp310/cp311/cp312/cp313`)
+- [ ] Confirm release step is idempotent (re-run does not fail)
+
+## 4. Release Assets
+- [ ] Confirm 5 arm64 wheel assets exist on release page
+- [ ] Confirm `checksums.txt` is attached
+- [ ] Confirm `build-metadata.json` is attached
+- [ ] Spot-check one wheel install and `import dmPython`
+
+## 5. Post-release
+- [ ] Update `CHANGELOG.md` if needed
+- [ ] Verify release notes and links are correct
+- [ ] Record any incidents/fixes back into `PATCHES.md` or docs

scripts/check_third_party_patch.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+"""Validate local patched DM driver contract and patch docs."""
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+GO_MOD = ROOT / "dpi_bridge/go.mod"
+PATCH_DOC = ROOT / "dpi_bridge/third_party/chunanyong_dm/PATCHES.md"
+PATCH_FILE = ROOT / "dpi_bridge/third_party/chunanyong_dm/a.go"
+
+
+def fail(msg: str) -> None:
+    raise RuntimeError(msg)
+
+
+def require_contains(path: Path, needle: str) -> None:
+    text = path.read_text(encoding="utf-8")
+    if needle not in text:
+        fail(f"{path} missing expected content: {needle}")
+
+
+def main() -> int:
+    if not GO_MOD.exists():
+        fail(f"missing {GO_MOD}")
+    if not PATCH_DOC.exists():
+        fail(f"missing {PATCH_DOC}")
+    if not PATCH_FILE.exists():
+        fail(f"missing {PATCH_FILE}")
+
+    require_contains(GO_MOD, "replace gitee.com/chunanyong/dm => ./third_party/chunanyong_dm")
+
+    # Patch documentation should describe the actual patch point and its tests.
+    require_contains(PATCH_DOC, "File: `a.go`")
+    require_contains(PATCH_DOC, "Function: `dm_build_610`")
+    require_contains(PATCH_DOC, "test_clob_unicode_problem_patterns_roundtrip")
+    require_contains(PATCH_DOC, "test_clob_unicode_problem_patterns_subprocess_no_crash")
+
+    # Patch implementation invariants for unicode chunk-boundary fix.
+    require_contains(PATCH_FILE, "dm_build_610(")
+    require_contains(PATCH_FILE, "var dm_build_615 bytes.Buffer")
+    require_contains(PATCH_FILE, "Avoid splitting a UTF-8 sequence at chunk boundaries.")
+
+    print("[OK] third-party patch consistency checks passed")
+    return 0
+
+
+if __name__ == "__main__":
+    try:
+        raise SystemExit(main())
+    except RuntimeError as exc:
+        print(f"[FAIL] {exc}")
+        raise SystemExit(2)