Semver y mantener un crate

En el nivel de Cargo miraste el versionado semántico desde abajo, como consumidor: serde = "1.0" era un rango y confiabas en que la mayor no rompería. Ser autor invierte la relación por completo. Ahora tú firmas esa promesa en cada cargo publish, y el ecosistema entero la da por buena: miles de Cargo.lock presumirán que tu 1.4.0 no romperá lo que funcionaba en 1.3.0. El problema es que «romper» en Rust significa mucho más de lo que la intuición sugiere. No es solo borrar una función: añadir una variante a un enum, un campo a un struct, un método a un trait —gestos que suenan aditivos e inocentes— puede invalidar el código de tus usuarios en silencio. Mantener un crate es, sobre todo, desarrollar el ojo para ver dónde acecha una ruptura, y aprender las herramientas que la contienen o la delatan antes de publicarla.

Qué cuenta como romper: el catálogo incómodo

La referencia de Cargo dedica un capítulo entero a catalogar los cambios que rompen, y leerlo es descubrir cuántos parecían seguros. La intuición «añadir no rompe, quitar sí» es falsa en Rust, porque el compilador razona sobre exhaustividad, inferencia y coherencia. Los casos que más sorprenden:

• Añadir una variante a un enum público es mayor: invalida todos los match exhaustivos de tus usuarios, que dejarán de compilar por no cubrir el nuevo caso.
• Añadir un campo a un struct de campos públicos es mayor: rompe la construcción por literal Struct { .. } y los patrones exhaustivos.
• Añadir un método a un trait sin implementación por defecto es mayor: los impl de tus usuarios ya no satisfacen el trait. Con un default, en cambio, suele ser menor.
• Endurecer un límite genérico (pedir un T: Clone que antes no exigías) es mayor; relajarlo es menor.
• Añadir un supertrait, sellar un trait, o quitarle Send a un tipo son rupturas, aunque no toques ninguna firma visible a simple vista.

Y luego lo obvio: renombrar o eliminar cualquier elemento pub, cambiar una firma, alterar un tipo de retorno. La lección es que tu API pública no son solo tus firmas: es todo lo observable por el código aguas abajo, incluida la forma en que encaja con la inferencia y la exhaustividad del compilador.

// v1.0.0
pub enum Estado { Activo, Inactivo }

// v1.1.0 -> ESTO ROMPE: un match exhaustivo del usuario ya no cubre todo
pub enum Estado { Activo, Inactivo, Suspendido }

Herramientas de compatibilidad: non_exhaustive y deprecated

Rust no te deja indefenso ante el catálogo anterior: ofrece atributos para diseñar la evolución. El primero, #[non_exhaustive], se anticipa a la ruptura más común —crecer un enum o un struct—:

#[non_exhaustive]
pub enum Error { Io, Sintaxis, Rango }

Marcar así un tipo obliga a tus usuarios, desde el día uno, a incluir un brazo comodín _ => en sus match y les impide construirlo por literal. A cambio, añadir variantes o campos en el futuro deja de ser una ruptura: reservas por diseño el derecho a crecer. Es un intercambio consciente —menos ergonomía para ellos hoy, estabilidad para todos mañana— idóneo en tipos que sabes que crecerán, como los enum de error.

El segundo es #[deprecated], que sustituye la ruptura por una transición guiada:

#[deprecated(since = "1.4.0", note = "usa `parse_str` en su lugar")]
pub fn parse(s: &str) -> Config { /* ... */ }

Deprecar no elimina: la función sigue ahí y funcionando, pero cada uso emite una advertencia con tu nota. Das a tus usuarios tiempo y una ruta clara para migrar antes de que la próxima mayor la retire de verdad. Un ciclo de deprecación —deprecar en 1.4, eliminar en 2.0— es la diferencia entre un mantenedor considerado y uno que rompe por sorpresa.

Verificar y honrar el contrato

El semver es una promesa difícil de cumplir a ojo: ya viste que las rupturas se esconden en gestos aditivos. Por eso existe cargo-semver-checks, que compara la API pública de tu código con la de la última versión publicada y te dice si el salto que planeas es coherente:

cargo install cargo-semver-checks
cargo semver-checks check-release        # analiza cientos de reglas de compatibilidad

Si intentas publicar un 1.5.0 que en realidad rompe, la herramienta lo detecta y exige que sea 2.0.0. Integrarla en CI transforma la etiqueta semver de cortesía frágil en una garantía verificada por máquina, como un compilador de tu propia disciplina de versiones.

Más allá de la herramienta, hay expectativas que la comunidad da por sentadas. Un CHANGELOG.md legible por humanos, que el semver por sí solo no reemplaza. Una política de MSRV (rust-version) explícita: subir el compilador mínimo es un cambio con impacto y suele anunciarse, muchos lo tratan como al menos una minor. Y atención a la seguridad: la base de datos RustSec y cargo audit rastrean vulnerabilidades por versión, y publicar un aviso cuando descubres un fallo grave es parte del deber de mantener.

flowchart TD
A[Vas a publicar una nueva version] --> B{cargo-semver-checks analiza la API}
B -->|API compatible| C[Sube MINOR o PATCH]
B -->|Detecta ruptura| D[Obliga a subir la MAYOR]
C --> E[Actualiza el CHANGELOG]
D --> E
E --> F{Vas a retirar algo}
F -->|Primero| G[Deprecar con nota y aviso]
G --> H[Eliminar en la siguiente MAYOR]
style B fill:#89b4fa,color:#11111b
style D fill:#f38ba8,color:#11111b
style G fill:#f9e2af,color:#11111b
style H fill:#a6e3a1,color:#11111b