From 3440512951e7cd1d9364592fb6c78a695c9e0d9f Mon Sep 17 00:00:00 2001 From: DataDave-Dev <153755137+DataDave-Dev@users.noreply.github.com> Date: Thu, 2 Jul 2026 10:56:05 -0600 Subject: [PATCH] docs: state a deprecation policy for 1.0.0 onward One minor of notice: anything in the public contract is deprecated with a warning for at least one minor release and removed only in the next major, so no 1.x upgrade breaks a rule file, bundle, or check script without notice. Stated user-facing in the README Stability & versioning section and operationally in documentation/releasing.md (both EN + ES). --- CHANGELOG.md | 4 ++++ README.es.md | 16 ++++++++++++++-- README.md | 15 ++++++++++++++- documentation/releasing.es.md | 17 +++++++++++++++++ documentation/releasing.md | 16 ++++++++++++++++ 5 files changed, 65 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index cbb3682..222fdaa 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -24,6 +24,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 exit codes (`0` pass · `1` a blocking rule failed · `2` config/usage problem) and the `check --json` output shape, both now locked by tests so a change is a deliberate break rather than a silent drift. +- Stated a **deprecation policy** for `1.0.0` on (README + `documentation/releasing.md`): + anything in the public contract is deprecated with a warning for at least one + minor and removed only in the next major, so no `1.x` upgrade breaks a rule + file, bundle, or check script without notice. ## [0.4.0] — 2026-07-01 diff --git a/README.es.md b/README.es.md index bf1c37f..a937101 100644 --- a/README.es.md +++ b/README.es.md @@ -515,10 +515,22 @@ de arriba no va a necesitar un cambio que rompa compatibilidad: pendientes. - [x] Documentar y estabilizar los códigos de salida de la CLI y la forma de `check --json`. -- [ ] Definir una política de deprecación: una release menor de aviso antes de - quitar cualquier cosa. +- [x] Definir una política de deprecación (abajo). - [ ] Validar en repos reales más allá de este. +**Política de deprecación** — desde `1.0.0`, nada del contrato público se quita +sin un major de aviso de por medio. Cuando algo tiene que cambiar: + +1. Se marca como **deprecado** en una release menor — sigue funcionando y emite + un warning. +2. Sigue funcionando (con el warning) durante el resto de esa serie mayor. +3. Se quita solo en la siguiente release **mayor**. + +Así, lo que es válido en `1.0` sigue válido en cada `1.x`: un cambio que rompe +compatibilidad siempre cruza una versión mayor, con al menos un minor de aviso +antes. Fijá una versión en CI y una actualización dentro de `1.x` nunca romperá +tus reglas, bundles ni scripts de check sin avisar. + ## Roadmap becwright es chico a propósito. En el horizonte: diff --git a/README.md b/README.md index 0343dcb..c3a71ae 100644 --- a/README.md +++ b/README.md @@ -542,9 +542,22 @@ need a breaking change: (`schema_version`). - [ ] Freeze the `rules.yaml` field set — no pending schema changes. - [x] Document and stabilize CLI exit codes and the `check --json` shape. -- [ ] State a deprecation policy: one minor release of notice before any removal. +- [x] State a deprecation policy (below). - [ ] Validate on real repositories beyond this one. +**Deprecation policy** — from `1.0.0` on, nothing in the public contract is +removed without a major bump of notice. When something has to change: + +1. It is marked **deprecated** in a minor release — it keeps working and emits a + warning. +2. It keeps working (still warning) through the rest of that major series. +3. It is removed only in the next **major** release. + +So anything valid on `1.0` stays valid across every `1.x`: a breaking change +always crosses a major version, with at least one minor of warning first. Pin a +version in CI and a `1.x` upgrade will never break your rules, bundles, or check +scripts without warning. + ## Roadmap becwright is intentionally small. On the horizon: diff --git a/documentation/releasing.es.md b/documentation/releasing.es.md index 79fab19..ef3d1c2 100644 --- a/documentation/releasing.es.md +++ b/documentation/releasing.es.md @@ -34,6 +34,23 @@ becwright se distribuye por tres canales desde un único release de GitHub: - publica primero los paquetes de plataforma y luego el lanzador, - construye y publica el paquete de Python en PyPI. +## Compatibilidad (desde 1.0.0) + +Una vez que salga `1.0.0`, el contrato público (el esquema de `rules.yaml`, el +formato de bundle `.bec.yaml`, los nombres y flags de los checks integrados, los +comandos y códigos de salida de la CLI, la forma de `check --json` y las firmas +de las herramientas MCP) sigue una **política de deprecación con un minor de +aviso**: + +- Nunca quitar ni romper nada del contrato dentro de un minor o un patch. +- Para retirar algo, marcarlo **deprecado** en un minor (sigue funcionando y + avisa), y quitarlo solo en el **siguiente major**. +- Un cambio que rompería un archivo de reglas, bundle o script de check de `1.x` + va en un bump mayor, no en un minor. + +Ver la [sección Estabilidad y versionado del README](../README.es.md#estabilidad-y-versionado) +para la declaración de cara al usuario. + ## Notas - Los paquetes de plataforma se publican antes que el lanzador para que sus diff --git a/documentation/releasing.md b/documentation/releasing.md index 00b24a2..974b46e 100644 --- a/documentation/releasing.md +++ b/documentation/releasing.md @@ -34,6 +34,22 @@ becwright ships through three channels from a single GitHub release: - publishes the platform packages first, then the launcher, - builds and publishes the Python package to PyPI. +## Compatibility (from 1.0.0 on) + +Once `1.0.0` ships, the public contract (the `rules.yaml` schema, the `.bec.yaml` +bundle format, built-in check names and flags, CLI commands and exit codes, the +`check --json` shape, and MCP tool signatures) follows a **one-minor-of-notice +deprecation policy**: + +- Never remove or break anything in the contract inside a minor or patch. +- To retire something, mark it **deprecated** in a minor (it keeps working and + warns), then remove it only in the **next major**. +- A change that would break a `1.x` rule file, bundle, or check script belongs in + a major bump, not a minor. + +See the [README's Stability & versioning section](../README.md#stability--versioning) +for the user-facing statement. + ## Notes - Platform packages are published before the launcher so the launcher's