chore: release 3.0.0

Author: ruicore

CHANGELOG.md

@@ -4,19 +4,28 @@ 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.
 
-## [3.0.0a0] - 2026-05-30
+## [3.0.0] - 2026-06-23
 
-This is a breaking 3.0 alpha release focused on a cleaner public API and module
-layout.
+This is the first stable ExcelAlchemy 3.0 release. It finalizes the breaking
+3.0 public API, documentation set, examples, and release validation path around
+typed Pydantic models plus explicit workbook metadata.
+
+### Added
+
+- Added stable 3.0 guidance across README, PyPI README, Chinese README,
+  public API docs, migration notes, examples, and generated output smoke checks.
+- Added release smoke coverage for package install behavior, repository
+  examples, docs assets, and API payload snapshots.
 
 ### Changed
 
 - Use the 3.0 public API from `excelalchemy`, `excelalchemy.config`,
   `excelalchemy.codecs`, `excelalchemy.storage`, and related public modules.
 - Internal modules now use explicit responsibility names such as `runtime`,
-  `schema`, `workbook`, `rendering`, `adapters`, and `primitives`.
+  `schema`, `worksheet`, `rendering`, `adapters`, and `primitives`.
 - Storage configuration uses `storage=...` with an `ExcelStorage`
   implementation.
+- Package metadata now marks the 3.0 line as a stable release.
 
 ### Removed
 
@@ -37,6 +46,15 @@ layout.
 - Removed legacy Minio config fields such as `minio`, `bucket_name`, and
   `url_expires`.
 
+### Migration Notes
+
+- 3.0 intentionally does not preserve 2.x compatibility imports, field
+  factories, config aliases, or facade aliases.
+- Python annotations define the data shape, Pydantic `Field(...)` defines
+  Pydantic validation, and `ExcelColumn(...)` defines workbook-facing metadata.
+- Use `docs/migrations.md` and `docs/public-api.md` as the current upgrade and
+  public surface references.
+
 ## [2.4.0] - 2026-04-24
 
 ### Added

README-pypi.md

@@ -11,8 +11,8 @@ ExcelAlchemy turns Pydantic models into workbook contracts:
 - return result workbooks and API-friendly error payloads
 - keep workbook IO pluggable through `ExcelStorage`
 
-The current mainline is ExcelAlchemy 3.0. It uses ordinary Python annotations
-plus explicit `ExcelColumn(...)` metadata. Old 2.x field factories,
+The current stable release is ExcelAlchemy 3.0. It uses ordinary Python
+annotations plus explicit `ExcelColumn(...)` metadata. Old 2.x field factories,
 compatibility imports, legacy config fields, and facade aliases are not current
 API.
 

README.md

@@ -21,10 +21,10 @@ Use it when you want to turn Python models into Excel workbook contracts:
 - return user-friendly result workbooks
 - keep storage pluggable through `ExcelStorage`
 
-The current mainline is ExcelAlchemy 3.0. It uses ordinary Python annotations
-plus explicit `ExcelColumn(...)` metadata. The old 2.x field factories,
-compatibility imports, legacy config fields, and facade aliases are not current
-API.
+The current stable release is ExcelAlchemy 3.0. It uses ordinary Python
+annotations plus explicit `ExcelColumn(...)` metadata. The old 2.x field
+factories, compatibility imports, legacy config fields, and facade aliases are
+not current API.
 
 ## Why This Matters
 

README_cn.md

@@ -14,7 +14,7 @@ ExcelAlchemy 是一个基于 Pydantic 模型的 schema-driven Excel 导入/导
 - 生成面向用户的结果工作簿
 - 通过 `ExcelStorage` 支持可替换的存储实现
 
-当前主线是 ExcelAlchemy 3.0。3.0 使用普通 Python 类型标注配合显式
+当前稳定版本是 ExcelAlchemy 3.0。3.0 使用普通 Python 类型标注配合显式
 `ExcelColumn(...)` 元数据。2.x 的字段工厂、兼容导入、legacy 配置字段和
 facade 别名都不再是当前 API。
 

docs/releases/3.0.0.md

@@ -0,0 +1,72 @@
+# 3.0.0 Release Notes and Checklist
+
+This document records the final release positioning and verification checklist
+for the stable `3.0.0` release.
+
+## Purpose
+
+- publish the first stable ExcelAlchemy 3.0 package
+- finalize the breaking 3.0 public API around typed Pydantic models and
+  explicit `ExcelColumn(...)` workbook metadata
+- confirm current docs, examples, and smoke assets describe 3.0 instead of the
+  retired 2.x compatibility surface
+- trigger the GitHub Release workflow that builds, verifies, and publishes the
+  Python package to PyPI
+
+## Release Positioning
+
+`3.0.0` is a stable breaking release:
+
+- Python type annotations define the data shape
+- Pydantic `Field(...)` stays responsible for Pydantic validation
+- `ExcelColumn(...)` carries workbook-facing metadata
+- codec helpers are explicit objects instead of fake Python scalar/container
+  types
+- storage configuration uses `storage=...` with an `ExcelStorage`
+  implementation
+- 2.x compatibility imports, legacy config fields, and facade aliases are no
+  longer current API
+
+## Before Tagging
+
+1. Confirm the package version in `src/excelalchemy/__init__.py` is `3.0.0`.
+2. Confirm `pyproject.toml` no longer marks the package as alpha.
+3. Review the `3.0.0` section in `CHANGELOG.md`.
+4. Confirm README entry points describe ExcelAlchemy 3.0 as stable:
+   - `README.md`
+   - `README-pypi.md`
+   - `README_cn.md`
+5. Confirm the release smoke scripts:
+   - `scripts/smoke_package.py`
+   - `scripts/smoke_examples.py`
+   - `scripts/smoke_docs_assets.py`
+   - `scripts/smoke_api_payload_snapshot.py`
+
+## Local Verification
+
+Run these commands from the repository root:
+
+```bash
+uv run ruff format --check .
+uv run ruff check .
+uv run pyright
+uv run pytest --cov=excelalchemy --cov-report=term-missing:skip-covered tests
+uv run python scripts/smoke_package.py
+uv run python scripts/smoke_examples.py
+uv run python scripts/smoke_docs_assets.py
+uv run python scripts/smoke_api_payload_snapshot.py
+uv build
+uvx twine check dist/*
+```
+
+## GitHub Release Steps
+
+1. Push the release commit.
+2. Create and publish the tag `v3.0.0`.
+3. Publish a GitHub Release for `v3.0.0` using this document and the
+   `CHANGELOG.md` entry as release-note sources.
+4. Confirm the `Upload Python Package` workflow succeeds.
+5. Confirm the published package version is `3.0.0`.
+
+The publish workflow verifies that the release tag, after removing the `v`
+prefix, matches `excelalchemy.__version__`.

pyproject.toml

@@ -10,7 +10,7 @@ readme = { file = 'README-pypi.md', content-type = 'text/markdown' }
 license = { file = 'LICENSE' }
 keywords = ['excel', 'openpyxl', 'pydantic', 'minio', 'schema']
 classifiers = [
-    'Development Status :: 3 - Alpha',
+    'Development Status :: 5 - Production/Stable',
     'Intended Audience :: Developers',
     'License :: OSI Approved :: MIT License',
     'Operating System :: OS Independent',

src/excelalchemy/__init__.py

@@ -1,6 +1,6 @@
 """Public ExcelAlchemy API."""
 
-__version__ = '3.0.0a0'
+__version__ = '3.0.0'
 from excelalchemy.artifacts import ExcelArtifact
 from excelalchemy.codecs.boolean import BooleanCodec
 from excelalchemy.codecs.choice import MultiChoiceCodec, SingleChoiceCodec