release: prepare ExcelAlchemy 2.2.8

[ruicore]

Summary

This PR prepares the 2.2.8 release of ExcelAlchemy.

It continues the stable 2.x line with a clearer integration reading path, stronger import-failure payload verification, and more direct install-time smoke coverage for the FastAPI reference app.

What changed

Documentation guidance

• add docs/integration-roadmap.md
• give first-time adopters a role-based reading path for:
  • first integration
  • backend API work
  • frontend error rendering
  • copyable reference code
  • migration and compatibility review
• link the roadmap from README, PyPI README, getting-started, and public API docs

Release smoke hardening

• add scripts/smoke_api_payload_snapshot.py
• generate and verify a stable import-failure payload snapshot at:
  • files/example-outputs/import-failure-api-payload.json
• extend CI and publish workflows to check that snapshot
• run python -m examples.fastapi_reference.app directly during install-time release verification

Release prep

• add the 2.2.8 changelog entry
• add docs/releases/2.2.8.md

Compatibility notes

• no public import/export workflow API was removed
• ImportResult, CellErrorMap, and RowIssueMap remain stable public result objects in 2.x
• storage=... remains the recommended 2.x backend configuration path

Verification

• ./.venv/bin/ruff check .
• ./.venv/bin/uv run pyright
• ./.venv/bin/pytest tests/integration/test_examples_smoke.py tests/contracts/test_result_contract.py -q
• ./.venv/bin/python scripts/generate_example_output_assets.py
• ./.venv/bin/python scripts/smoke_api_payload_snapshot.py
• ./.venv/bin/python scripts/smoke_docs_assets.py
• ./.venv/bin/uv run --with fastapi --with httpx --with python-multipart python -m examples.fastapi_reference.app

Release intent

After merge, this branch is intended to be tagged and published as:

• v2.2.8

[codecov]

Codecov Report

❌ Patch coverage is 94.02985% with 4 lines in your changes missing coverage. Please review.
✅ Project coverage is 87.48%. Comparing base (dee5649) to head (9c71a63).
⚠️ Report is 9 commits behind head on main.

Files with missing lines	Patch %	Lines
src/excelalchemy/core/alchemy.py	66.66%	2 Missing ⚠️
src/excelalchemy/_primitives/diagnostics.py	94.44%	1 Missing ⚠️
src/excelalchemy/metadata.py	75.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #68      +/-   ##
==========================================
+ Coverage   87.06%   87.48%   +0.41%     
==========================================
  Files          48       49       +1     
  Lines        3882     3938      +56     
  Branches      431      431              
==========================================
+ Hits         3380     3445      +65     
+ Misses        313      306       -7     
+ Partials      189      187       -2     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c71a63219

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Run snapshot verification before regenerating the snapshot

scripts/generate_example_output_assets.py now rewrites files/example-outputs/import-failure-api-payload.json, and this workflow invokes it immediately before scripts/smoke_api_payload_snapshot.py; that makes the smoke check compare against a just-regenerated file instead of the committed baseline, so API payload contract regressions can slip through unnoticed. I checked the same ordering in both ci.yml and python-publish.yml, so the release smoke currently gives a false sense of snapshot stability.

Useful? React with 👍 / 👎.