release-prep: finalize v0.2.0 hardening policy and release notes

Author: GSstarGamer

CHANGELOG.md

@@ -0,0 +1,41 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+This format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+and versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-02-23
+
+### Added
+
+- WebSocket v2 bridge protocol, transport metadata, and auth/session framing as the standard bridge path.
+- Typed API substrate (`api.metadata.get`, `api.construct`, `api.invoke`) with Python typed wrappers under `client.baritone.*`.
+- Minecraft identifier constants under `pyritone.minecraft.blocks`, `pyritone.minecraft.items`, and `pyritone.minecraft.entities`.
+- Release parity and fallback debt report: `python/docs/release-parity-fallback-report.md`.
+- Async-only release notes: `docs/release-notes-v0.2.0.md`.
+
+### Changed
+
+- Python client direction is async-only with `pyritone.Client` as the canonical entry point.
+- Docs and demos were migrated to async class-oriented usage (`async with Client()`).
+- Generated command docs now use async-only examples.
+- Mod and Python package versions were bumped to `0.2.0` for this release line.
+
+### Removed
+
+- Legacy socket bridge server code path from the mod runtime.
+- Legacy sync-labeled user docs/examples (`python/docs/sync-client.md`, `python/example_sync.py`).
+
+### Compatibility Policy
+
+- `PyritoneClient` and `AsyncPyritoneClient` remain exported in `v0.2.x` as soft-deprecated aliases to `Client`.
+- Generated sync command shims (`python/src/pyritone/commands/sync_*.py`) remain in `v0.2.x` for migration cushioning.
+- `client.execute(...)` remains public as an advanced raw command escape hatch; user-facing docs should prefer generated command wrappers and typed APIs.
+- Planned removal target for alias/shim compatibility surfaces: no earlier than `v0.3.0`.
+
+## [0.1.2]
+
+- Last release before the async-only WebSocket v2 migration line.

README.md

@@ -68,6 +68,8 @@ python demos/01_connect_discovery.py
 
 - Async-only release checklist: `docs/release-checklist.md`
 - Parity/fallback debt snapshot: `python/docs/release-parity-fallback-report.md`
+- Release notes draft: `docs/release-notes-v0.2.0.md`
+- Changelog: `CHANGELOG.md`
 
 ## One-Click Dev Client
 

docs/release-checklist.md

@@ -25,13 +25,30 @@ Use this checklist before publishing a release from `feat/ws-v2-async`.
 - Confirm fallback debt gates are green:
   - `python/tests/test_fallback_debt.py`
 
-## 4. Versioning + Changelog
-
-- Record user-facing changes in changelog under an `Unreleased` (or release) section.
-- If compatibility aliases/shims are removed, treat as a breaking change release.
-- Ensure release notes call out websocket v2 + async-only client direction.
-
-## 5. Publish Readiness
+## 4. Compatibility Policy (v0.2.x Tag Decision)
+
+- Keep compatibility aliases exported in `v0.2.x`:
+  - `PyritoneClient -> Client`
+  - `AsyncPyritoneClient -> Client`
+- Keep generated sync command shim modules in `v0.2.x`:
+  - `python/src/pyritone/commands/sync_*.py`
+- Do not increase compatibility debt ceilings in `python/tests/test_fallback_debt.py`.
+- Keep `client.execute(...)` public as an advanced escape hatch for command interop and CLI usage.
+- Docs/quickstarts should prefer generated command wrappers and `client.baritone.*` typed APIs.
+- Removal target for aliases + sync shims: no earlier than `v0.3.0`.
+
+## 5. Versioning + Release Notes
+
+- Bump Python package version in:
+  - `python/pyproject.toml`
+- Bump mod version in:
+  - `mod/gradle.properties`
+- Record user-facing changes in:
+  - `CHANGELOG.md`
+- Publish release notes from Wave 9 outputs in:
+  - `docs/release-notes-v0.2.0.md`
+
+## 6. Publish Readiness
 
 - Build Python package:
   - `cd python && python -m build`

docs/release-notes-v0.2.0.md

@@ -0,0 +1,52 @@
+# Release Notes v0.2.0 (Async-Only + WebSocket v2)
+
+Release target for the `feat/ws-v2-async` migration line.
+
+## Highlights
+
+- WebSocket v2 is now the bridge transport baseline (`ws://127.0.0.1:27841/ws`).
+- `pyritone.Client` is the canonical async client API.
+- Typed Baritone wrappers are available under `client.baritone.*`.
+- Minecraft constants are available under `pyritone.minecraft.*`.
+- Docs/demos were rewritten to async-only usage.
+
+## Breaking Direction Changes
+
+- Sync runtime semantics were removed from the Python client path.
+- Bridge usage is now websocket-first (legacy socket bridge path removed).
+- New code should use:
+  - generated command wrappers (for command dispatch),
+  - typed wrappers (`client.baritone.*`) for richer API calls.
+
+## Compatibility Policy For v0.2.x
+
+- Keep compatibility aliases:
+  - `PyritoneClient -> Client`
+  - `AsyncPyritoneClient -> Client`
+- Keep generated sync command shim modules:
+  - `python/src/pyritone/commands/sync_*.py`
+- Treat both as soft-deprecated migration cushions; removal target is no earlier than `v0.3.0`.
+- Keep `client.execute(...)` available as an advanced raw-command escape hatch.
+  - Guidance: prefer wrapper/typed APIs in user-facing docs and new application code.
+
+## Parity + Debt Snapshot
+
+- Canonical command wrappers: `42`
+- Alias wrappers: `21`
+- Compatibility alias assignments: `3`
+- Sync command shim modules: `6`
+- Legacy socket bridge path: removed (guarded by tests)
+- Cancel fallback `"stop"` command path: removed (guarded by tests)
+
+Primary references:
+
+- `python/docs/release-parity-fallback-report.md`
+- `python/docs/baritone-typed-parity.md`
+- `docs/release-checklist.md`
+
+## Upgrade Notes
+
+1. Prefer importing `Client` from `pyritone`.
+2. Move command calls to awaited async flows (`await client.goto(...)`, etc.).
+3. Keep alias imports only as transitional compatibility while migrating existing codebases.
+4. Use `client.execute(...)` only when wrapper/typed surfaces do not cover the needed command flow.

docs/runbook.md

@@ -33,4 +33,4 @@ pyritone --host 127.0.0.1 --port 27841 --token <token> ping
 
 ## Not In World
 
-- Connect to any singleplayer or multiplayer world before running `baritone.execute`.
+- Connect to any singleplayer or multiplayer world before dispatching Baritone commands (wrapper methods or advanced `client.execute(...)`).

mod/gradle.properties

@@ -14,6 +14,6 @@ fabric_version=0.136.1+1.21.8
 baritone_version=1.15.0
 
 # Mod properties
-mod_version=0.1.0
+mod_version=0.2.0
 maven_group=com.pyritone
 archives_base_name=pyritone_bridge

python/README.md

@@ -74,6 +74,7 @@ python demos/01_connect_discovery.py
   - Legacy aliases (`PyritoneClient`, `AsyncPyritoneClient`) are compatibility-only; use `Client` in docs and new code.
 - Low-level methods:
   - `ping`, `status_get`, `status_subscribe`, `status_unsubscribe`, `execute`, `cancel`, `next_event`, `wait_for`, `wait_for_task`
+  - `execute(...)` is an advanced raw command path; prefer generated command wrappers and typed APIs in new code.
   - Typed API substrate: `api_metadata_get`, `api_construct`, `api_invoke`
 - Typed Baritone wrappers:
   - `client.baritone` root namespace over Wave 4 typed calls
@@ -102,6 +103,13 @@ python demos/01_connect_discovery.py
 - Typed remote references:
   - `RemoteRef(ref_id=..., java_type=...)` values returned by `api_construct` / `api_invoke`
 
+## Compatibility Policy (v0.2.x)
+
+- `PyritoneClient` and `AsyncPyritoneClient` remain exported as temporary compatibility aliases.
+- Generated sync command shim modules (`python/src/pyritone/commands/sync_*.py`) remain for migration cushioning.
+- Both compatibility surfaces are soft-deprecated and planned for removal no earlier than `v0.3.0`.
+- Keep new docs/examples on `Client` + async command/typed APIs; use raw `execute(...)` only for advanced/interop cases.
+
 ## Auto-Discovery (Zero-Setup)
 
 By default, `pyritone` discovers bridge metadata from:

python/docs/migration-from-legacy-aliases.md

@@ -30,6 +30,14 @@ PyritoneClient and AsyncPyritoneClient are temporary compatibility aliases to Cl
 All client methods are async and must be awaited.
 ```
 
+### Compatibility window
+
+```text
+Release policy for v0.2.x keeps these aliases and generated sync command shims
+as soft-deprecated migration cushions.
+Planned removal target: no earlier than v0.3.0.
+```
+
 ### Common mistakes
 
 - Keeping old import names in new docs/examples.

python/docs/release-parity-fallback-report.md

@@ -32,14 +32,22 @@ Remaining intentional debt:
 - Sync command shim modules are still generated for compatibility surfaces.
 - Raw command transport (`baritone.execute`) is retained for command-wrapper interop and edge usage.
 
+## Tag Policy Decision (v0.2.0)
+
+- Keep compatibility aliases in public exports for `v0.2.x`:
+  - `PyritoneClient -> Client`
+  - `AsyncPyritoneClient -> Client`
+- Keep generated sync command shim modules for `v0.2.x`:
+  - `python/src/pyritone/commands/sync_*.py`
+- Treat both as soft-deprecated migration cushions and keep debt ceilings flat:
+  - alias assignments `<= 3`
+  - sync shim modules `<= 6`
+- Keep `client.execute(...)` public for advanced command interop and CLI usage, but position it as advanced-only in docs.
+- Prefer generated command wrappers and typed `client.baritone.*` APIs in user-facing examples.
+- Removal target for aliases + sync shims: no earlier than `v0.3.0`.
+
 ## Release Readiness Notes
 
 - Docs and demos now present `pyritone.Client` as the primary client.
 - Sync-labeled usage guides/examples were removed from user-facing docs.
 - Migration guidance is isolated in `python/docs/migration-from-legacy-aliases.md`.
-
-## Recommended Next Cleanup Before Major Release
-
-1. Remove compatibility aliases from public exports.
-2. Stop generating sync command shim modules.
-3. Re-evaluate whether `baritone.execute` should remain public or move to advanced-only guidance.

python/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyritone"
-version = "0.1.2"
+version = "0.2.0"
 description = "Python client for the Py-Ritone Baritone bridge"
 readme = "README.md"
 requires-python = ">=3.10"