# Release & Compatibility Policy

This document defines the minimum release contract for production use.

## Versioning (SemVer)

Guren uses Semantic Versioning for stable releases:

- **MAJOR**: incompatible API or behavioral changes
- **MINOR**: backward-compatible features
- **PATCH**: backward-compatible bug fixes and security updates

From `1.0`, breaking changes ship only in major releases; minors and patches are backward compatible. Every breaking change must be documented in migration notes.

## Runtime Compatibility Matrix

| Runtime | Supported | Notes |
| --- | --- | --- |
| Bun `1.3.x` | Yes (primary) | CI and release workflows run on Bun `1.3.1` |
| Node.js `20.x` | Tooling compatibility only | For docs/build tooling where applicable |
| Node.js `22.x` | Tooling compatibility only | For docs/build tooling where applicable |

If the matrix changes, update this guide and `CHANGELOG.md` in the same PR.

## Backward Compatibility Rules

- Public exports in `@guren/*` are considered API surface.
- Removing or changing public types/behavior requires:
  - a migration section in the release notes
  - a deprecation path when feasible
  - tests covering old/new behavior boundaries

## Release Cadence & Notes

- Every release must include changelog/release notes.
- Notes must include at least:
  - Added / Changed / Fixed
  - Breaking changes (if any)
  - Migration steps
  - Runtime compatibility changes

## Upgrade Documentation Requirement

Each minor release must have an upgrade entry in `docs/en/guides/upgrading.md` and `docs/ja/guides/upgrading.md`.