feat(v2.2): runtime consolidation release

Author: ruicore

CHANGELOG.md

@@ -4,6 +4,50 @@ All notable changes to this project will be documented in this file.
 
 The format is inspired by Keep a Changelog and versioned according to PEP 440.
 
+## [2.2.0] - Unreleased
+
+This release continues the stable 2.x line with runtime consolidation,
+clearer configuration ergonomics, and a stronger protocol-first storage story.
+
+### Added
+
+- Added `ImportSessionPhase` and `ImportSessionSnapshot` so one-shot import runs
+  expose a clearer lifecycle and final runtime summary
+- Added recommended config constructors:
+  `ImporterConfig.for_create(...)`, `ImporterConfig.for_update(...)`,
+  `ImporterConfig.for_create_or_update(...)`, `ExporterConfig.for_model(...)`,
+  and `ExporterConfig.for_storage(...)`
+- Added targeted regression tests for config helper constructors, legacy
+  storage deprecation behavior, and import session snapshots
+
+### Changed
+
+- Refined `ImportSession` so the import workflow now advances through explicit
+  phases: workbook loading, header validation, row preparation, row execution,
+  result rendering, and completion
+- Added `ExcelAlchemy.last_import_snapshot` as the facade-level read-only view
+  of the latest import session state
+- Clarified the recommended storage configuration path around explicit
+  `storage=...` backends
+- Kept legacy `minio`, `bucket_name`, and `url_expires` support for 2.x, but
+  now emit an explicit deprecation warning when that path is used
+- Reduced warning noise by emitting the legacy storage deprecation warning once
+  per compatibility scenario
+
+### Compatibility Notes
+
+- No public import or export workflow API was removed in this release
+- The legacy Minio config path remains supported in 2.x for migration-friendly
+  compatibility
+- Existing direct `ImporterConfig(...)` and `ExporterConfig(...)` construction
+  continue to work; helper constructors are the new recommended path
+
+### Release Summary
+
+- import sessions now expose a clearer lifecycle and final snapshot
+- config construction is easier to read through dedicated helper constructors
+- `storage=...` is now the clear recommended backend integration path for 2.x
+
 ## [2.1.0] - 2026-04-02
 
 This release continues the stable 2.x line with internal architecture cleanup,

docs/releases/2.2.0.md

@@ -0,0 +1,119 @@
+# 2.2.0 Release Checklist
+
+This checklist is intended for the `2.2.0` release on top of the stable 2.x
+line.
+
+## Purpose
+
+- publish the next stable 2.x refinement release of ExcelAlchemy
+- present `2.2.0` as a runtime-consolidation and developer-ergonomics release
+- keep the public 2.x workflow stable while making the internal import runtime
+  more explicit
+- reinforce `storage=...` as the recommended backend integration path
+
+## Release Positioning
+
+`2.2.0` should be presented as an architectural refinement release:
+
+- the public import and export workflow API stays stable
+- import runs now expose a clearer lifecycle through `ImportSession`
+- config construction is easier to read through dedicated helper constructors
+- storage integration becomes more clearly protocol-first without breaking 2.x
+  compatibility
+
+## Before Tagging
+
+1. Confirm the intended version in `src/excelalchemy/__init__.py`.
+2. Review the `2.2.0` section in `CHANGELOG.md`.
+3. Confirm `README.md`, `README-pypi.md`, and `MIGRATIONS.md` still describe
+   the recommended public paths correctly.
+4. Confirm `README_cn.md` remains aligned with the current release position.
+5. Confirm the compatibility notes for:
+   - `minio / bucket_name / url_expires`
+   - `storage=...` as the recommended path
+   - `df/header_df` compatibility aliases
+   - `excelalchemy.util.convertor`
+
+## Local Verification
+
+Run these commands from the repository root:
+
+```bash
+uv sync --extra development
+uv run ruff check .
+uv run pyright
+uv run pytest tests
+rm -rf dist
+uv build
+uvx twine check dist/*
+```
+
+Optional smoke tests:
+
+```bash
+uv venv .pkg-smoke-base --python 3.14
+uv pip install --python .pkg-smoke-base/bin/python dist/*.whl
+.pkg-smoke-base/bin/python -c "import excelalchemy; print(excelalchemy.__version__)"
+```
+
+```bash
+uv venv .pkg-smoke-minio --python 3.14
+uv pip install --python .pkg-smoke-minio/bin/python "dist/*.whl[minio]"
+.pkg-smoke-minio/bin/python -c "from excelalchemy.core.storage_minio import MinioStorageGateway; print(MinioStorageGateway.__name__)"
+```
+
+## GitHub Release Steps
+
+1. Push the release commit to the default branch.
+2. In GitHub Releases, draft a new release.
+3. Create a new tag: `v2.2.0`.
+4. Use the `2.2.0` section from `CHANGELOG.md` as the release notes base.
+5. Publish the release and monitor the `Upload Python Package` workflow.
+
+## Release Focus
+
+When reviewing the final release notes, make sure they communicate these three
+themes clearly:
+
+- `ImportSession` now exposes a clearer lifecycle and final session snapshot
+- config construction is easier to read through dedicated helper constructors
+- explicit `storage=...` is the clear recommended backend integration path for
+  the 2.x line
+
+## Recommended Release Messaging
+
+Prefer wording that emphasizes refinement and stability:
+
+- "continues the stable 2.x line"
+- "keeps the public import/export workflow API stable"
+- "clarifies the import runtime lifecycle"
+- "improves config ergonomics and backend integration guidance"
+
+## PyPI Verification
+
+After the workflow completes:
+
+1. Confirm the new release appears on PyPI.
+2. Confirm the long description renders correctly.
+3. Confirm screenshots and absolute links still work on the PyPI project page.
+4. Test base install:
+
+```bash
+pip install -U ExcelAlchemy
+```
+
+5. Test optional Minio install:
+
+```bash
+pip install -U "ExcelAlchemy[minio]"
+```
+
+6. Run one template-generation example.
+7. Run one import flow and one export flow.
+
+## Done When
+
+- the tag `v2.2.0` is published
+- the GitHub Release notes clearly communicate the three release themes
+- PyPI renders the project description correctly
+- CI, typing, tests, and package publishing all pass for the tagged release