docs(releases): document SDK compatibility and recovery

docs/README.md

@@ -131,3 +131,5 @@ See [Realtime](./realtime.md) for broadcasts, presence, database changes, and sh
 See [Authentication](./authentication.md) for account, session, email, and OAuth workflows.
 
 See [Functions](./functions.md) for invocation identity, response values, and error handling.
+
+See [Versions and compatibility](./versions.md) for runtime support, upgrades, and restoring a tested dependency set.

docs/versions.md

@@ -0,0 +1,53 @@
+---
+title: Python SDK versions
+description: Pin a tested SDK version, check runtime compatibility, upgrade safely, and restore a previous application dependency set.
+---
+
+Pin the SDK version your application has tested. For example:
+
+```text
+volcano-sdk-python==0.10.0
+```
+
+Save this requirement in your application dependency file and install it in a virtual environment.
+
+These are example versions, not a moving latest-version reference.
+Keep the resolved dependency lock used by your application and install from that lock in CI and deployment. An exact direct requirement alone does not lock transitive dependencies.
+
+## Runtime and compatibility
+
+Use Python 3.11 or later. Native CI tests Python 3.11 and 3.14; it does not test every intervening interpreter release. REST methods are synchronous, while realtime uses an asynchronous lifecycle.
+
+The package is currently on the 0.x release line. Treat a minor-version update as potentially incompatible and read its release notes before upgrading.
+JavaScript, Python and Ruby releases have independent version numbers; matching numbers are not a compatibility requirement.
+Python raises typed exceptions; JavaScript keeps its result-envelope API.
+Follow your language's public facade and examples rather than importing generated transport classes.
+
+The docs describe the current SDK source. Confirm a method is included in your installed version by checking its [release notes](https://github.com/Kong/volcano-sdk-python/releases) and [changelog](https://github.com/Kong/volcano-sdk-python/blob/main/CHANGELOG.md).
+Server-dependent features also need the corresponding Volcano API behavior; installing a newer SDK does not deploy that behavior.
+
+## Upgrade an application
+
+1. Read the release notes between your installed version and the intended version, including breaking changes and runtime requirements.
+2. Update the dependency in a branch and review the resolved lockfile changes.
+3. Run the [documented quickstart](./README.md) with a disposable test project, then run the application tests for the features you use.
+4. Deploy the tested application and dependency lock together. Retain the previous tested application revision and lock.
+
+A successful package import proves installation, not compatibility with every deployed API feature.
+
+## Restore a previous version
+
+Restore the previously tested application revision and its dependency lock together, then install from that lock in a clean environment.
+Run the same quickstart and application tests before redeploying it.
+Do not select an arbitrary older SDK version or downgrade only the top-level dependency while retaining a different transitive dependency tree.
+
+Restoring application packages does not revert server configuration, schema changes, stored data or completed operations.
+Check those dependencies before rolling back an application that changed them.
+
+## Report a compatibility problem
+
+Open an [SDK issue](https://github.com/Kong/volcano-sdk-python/issues) with the installed SDK version, runtime version, affected method, expected result and a minimal reproduction.
+Include a sanitized error category and status when available.
+Remove keys, tokens, passwords and private response bodies.
+
+For suspected vulnerabilities, including authentication or authorization regressions, follow [Kong’s vulnerability reporting process](https://konghq.com/compliance/vuln-disclosure) and email vulnerability@konghq.com. Do not post security reproductions in public issues, pull requests or discussions.

maintainers/releasing.md

@@ -0,0 +1,29 @@
+# Release evidence and recovery
+
+The checked-in release and publish workflows own versioning and publication.
+This checklist does not authorize a release, a registry mutation or an environment approval.
+
+## Before publication
+
+1. Identify the release PR, exact source commit, version, tag and intended registry account. Inspect the generated changelog and package metadata.
+2. Require passing native checks: `uv run python scripts/check_openapi.py`, Ruff, mypy, Pyright, `uv run pytest tests/unit -q`, `uv run python -m build`, and `bash scripts/check_package.sh`. Verify the OpenAPI snapshot and generated output using the checked-in commands.
+3. Obtain clean code and security reviews. Record the approved shared-acceptance run and exact Hosting/SDK revisions for behavior changes; dry runs and synthetic HTTP tests are not live acceptance.
+4. Build the wheel and source distribution locally, install it in a clean environment, and run the exact public quickstart. Retain its digest and inventory as candidate package-content evidence; this is not proof of the bytes the release workflow will later build.
+5. Confirm explicit release authorization before any publication action. The existing automatic release path may publish after a release PR lands; a successful check or an unprotected environment is not itself release approval. Resolve authorization before merging a release PR rather than assuming the configured PyPI environment has a human gate.
+
+Use the existing workflows and their tag, ancestry, identity and artifact checks.
+The release-triggered workflow builds after the GitHub release is published, then passes its preserved artifact to the registry job without rebuilding. A local candidate and the workflow artifact are separate builds. Authorize the source version and this workflow before triggering that path; do not claim exact-byte pre-publication approval from the local check. If approval of specific bytes is required, first add and review a build/test/approval boundary that holds that same artifact before publication. Do not retag a release or overwrite a published version.
+After publication, verify the registry's package identity and version, digest/provenance where available, clean installation, and the documented quickstart against the approved platform revision.
+Record the workflow URL and registry URL. Source-main tests alone do not prove the published artifact contains that source.
+
+## Recover from a bad release
+
+For an application regression, first restore its previously tested application revision and dependency lock using [the public guide](../docs/versions.md).
+Confirm compatibility with current server configuration and data; an SDK downgrade does not roll either back.
+
+Record the affected versions, symptom, safe previous version, artifact digests and any required data/server remediation in the incident or release issue.
+Prepare a reviewed fix as a new version. Do not republish altered bytes under an existing version.
+If package deprecation, yanking, an npm tag move or another registry action is needed, preview the exact package/version/action and obtain explicit release-owner authorization first.
+Keep already published artifacts and audit evidence available unless the approved response specifically requires otherwise.
+
+Before calling recovery verified, run clean installs and the affected application/quickstart checks for both the safe version and the proposed fix. Record actual results and remaining limits; a written rollback plan is not a performed rollback.