Está en la página 1de 4

Versionamiento Semntico 2.0.0rc.

2
En el mundo de la gestin de software existe el temor de caer en algn momento en el llamado infierno de
las dependencias. Mientras ms grande crece tu sistema y mientras ms paquetes integras en tu
software, ms probable es que te encuentres, un da, en este pozo de la desesperacin.
En sistemas con muchas dependencias, publicar nuevas versiones de un paquete puede transformarse
rpidamente en una pesadilla. Si las especificaciones de dependencia son muy estrictas est el peligro del
bloqueo de versiones (la imposibilidad de actualizar un paquete sin tener que actualizar todos los que
dependen de este). Si las dependencias se especifican de manera muy amplia, inevitablemente caers en
promiscuidad de versiones (asumir ms compatibilidad con versiones futuras de lo razonable). El infierno
de las dependencias es donde te encuentras cuando el bloqueo de versiones o la promiscuidad de
versiones te impiden avanzar en tu proyecto de manera fcil y segura.
Como solucin a este problema, propongo un set simple de reglas y requerimientos que dictan cmo
asignar y cmo aumentar los nmeros de versin. Para que este sistema funcione, tienes que declarar
primero un API pblica. Esto puede consistir en documentacin o ser explicitado en el cdigo mismo. De
cualquier forma, es importante que esta API sea clara y precisa. Una vez que identificaste tu API pblica,
comunicas cambios a ella con aumentos especficos al nmero de versin. Considera un formato de
versin del tipo X.Y.Z (Major.Minor.Patch) Los arreglos de bugs que no cambian el API incrementan el
patch, los cambios y adiciones que no rompen la compatibilidad de las dependencias anteriores
incrementan el minor, y los cambios que rompen la compatibilidad incrementan el major.
Yo llamo a este sistema Versionamiento Semntico. Bajo este esquema, los nmeros de versin y la
forma en que cambian entregan significado del cdigo que est detrs y lo que fue modificado de una
versin a otra.

Especificacin de Versionamiento Semntico (en ingls


SemVer)
En el documento original se usa el RFC 2119 para el uso de las palabras MUST, MUST NOT, SHOULD,
SOULD NOT y MAY. Para que la traduccin sea lo ms fiel posible, he traducido siempre MUST por el
verbo deber en presente (DEBE, DEBEN), SHOULD como el verbo deber en condicional (DEBERA,
DEBERAN) y el verbo MAY como el verbo PODER.
1.El software que use Versionamiento Semntico DEBE declarar una API pblica. Esta API puede ser
declarada en el cdigo mismo o existir en documentacin estricta. De cualquier manera, debera ser
precisa y completa.
2.Un nmero normal de versin DEBE tomar la forma X.Y.Z donde X, Y, y Z son enteros no negativos. X es
la versin major, Y es la versin minor, y Z es la versin patch. Cada elemento DEBE incrementarse
numricamente en incrementos de 1. Por ejemplo: 1.9.0 -> 1.10.0 -> 1.11.0.

3.Una vez que un paquete versionado ha sido liberado (release), los contenidos de esa versin NO
DEBEN ser modificadas. Cualquier modificacin DEBE ser liberada como una nueva versin.
4.La versin major en cero (0.y.z) es para desarrollo inicial. Cualquier cosa puede cambiar en cualquier
momento. El API pblica no debiera ser considerada estable.
5.La versin 1.0.0 define el API pblica. La forma en que el nmero de versin es incrementado despus
de este release depende de esta API pblica y de cmo esta cambia.
6.La versin patch Z (x.y.Z | x > 0) DEBE incrementarse cuando se introducen solo arreglos compatibles
con la versin anterior. Un arreglo de bug se define como un cambio interno que corrige un
comportamiento errneo.
7.La versin minor Y (x.Y.z | x > 0) DEBE ser incrementada si se introduce nueva funcionalidad compatible
con la versin anterior. Se DEBE incrementar si cualquier funcionalidad de la API es marcada como
deprecada. PUEDE ser incrementada si se agrega funcionalidad o arreglos considerables al cdigo
privado. Puede incluir cambios de nivel patch. La versin patch DEBE ser reseteada a 0 cuando la versin
minor es incrementada.
8.La versin major X (X.y.z | X > 0) DEBE ser incrementada si cualquier cambio no compatible con la
versin anterior es introducida a la API pblica. PUEDE incluir cambios de niver minor y/o patch. Las
versiones patch y minor DEBEN ser reseteadas a 0 cuando se incrementa la versin major.
9.Una versin pre-release PUEDE ser representada por adjuntar un guin y una serie de identificadores
separados por puntos inmediatamente despus de la versin patch. Los identificadores DEBEN consistir
solo de caracteres ASCII alfanumricos y el guin [0-9A-Za-z-]. Las versiones pre-release satisfacen pero
tienen una menor precedencia que la versin normal asociada.Ejemplos: 1.0.0-alpha, 1.0.0-alpha.1, 1.0.00.3.7, 1.0.0-x.7.z.92.
10.La metadata de build PUEDE ser representada adjuntando un signo ms y una serie de identificadores
separados por puntos inmediatamente despus de la versin patch o la pre-release. Los identificadores
DEBEN consistir slo de caracteres ASCII alfanumricos y el guin [0-9A-Za-z-]. Los meta-datos de build
DEBIERAN ser ignorados cuando se intenta determinar precedencia de versiones. Luego, dos paquetes
con la misma versin pero distinta metadata de build se consideran la misma versin. Ejemplos: 1.0.0alpha+001, 1.0.0+20130313144700, 1.0.0-beta+exp.sha.5114f85.
11.La precedencia DEBE ser calculada separando la versin en major, minor, patch e identificadores prerelease en ese orden (La metadata de build no figuran en la precedencia). Las versiones major, minor, y
patch son siempre comparadas numricamente. La precedencia de pre-release DEBE ser determinada
comparando cada identificador separado por puntos de la siguiente manera: los identificadores que solo
consisten de nmeros son comparados numricamente y los identificadores con letras o guiones son
comparados de acuerdo al orden establecido por ASCII. Los identificadores numricos siempre tienen una
precedencia menor que los no-numricos. Ejemplo: 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta.2 < 1.0.0beta.11 < 1.0.0-rc.1 < 1.0.0.

Por qu usar Versionamiento Semntico?


Esta no es una idea nueva o revolucionarias. De hecho, probablemente ya haces algo cercano hoy en da.
El problema es que cercano no es suficientemente bueno. Sin un acuerdo en algun tipo de especificacin
formal, los nmeros de versiones son esencialmente intiles para el manejo de dependencias. Al darle un
nombre y una definicin clara a las ideas expresadas arriba, se hace facil comunicar tus intenciones a los

usuarios de tu software. Una vez que estas intenciones son claras y flexibles (pero no demasiado flexibles)
finalmente se pueden hacer especificaciones de dependencias.
Un ejemplo simple puede demostrar como el Versionamiento Semntico puede ayudar a que el infierno de
dependencias quede en el pasado. Considera una librera llamada "CarroBomba" Requiere de un paquete
Semanticamente Versionado llamado Escalera. En el momento en que se crea CarroBomba, Escalera
est en su versin 3.1.0. Como CarroBomba usa algunas de las funcionalidades que recin se estrenaron
en la versin 3.1.0, puedes tranquilamente definir la dependencia de Escalera como mayor o igual a 3.1.0,
pero menor a 4.0.0. Ahora, cuando la versin 3.1.1 y 3.2.0 de Escalera sean liberadas, puedes usarlas en
tu sistema de versionamiento de paquetes sabiendo que sern compatibles con el software dependiente.
Como desarrollador responsable que eres, claro, querrs verificar que cualquier actualizacin de paquete
funcione como se anunci. El mundo real es complejo; no hay nada que podamos hacer salvo estar
atentos. Lo que puedes hacer es dejar que el Versionamiento Semntico te provea de una manera sana de
liberar y actualizar paquetes sin tener que entregar nuevas versiones de tus paquetes dependientes,
ahorrndote tiempo y molestias.
Si todo esto suena deseable, todo lo que tienes que hacer para comenzar usando Versionamiento
Semntico es declarar que lo ests haciendo y seguir las reglas. Haz un link a este sitio desde tu
README para que otros conozcan las reglas y se puedan beneficiar de ellas.

FAQ
Cmo tengo que hacer con las revisiones en la etapa inicial de desarrollo 0.y.z ?
Lo ms facil es empezar tu desarrollo inicial en 0.1.0 e incrementar la versin minor en cada release.

Cmo s cundo liberar la versin 1.0.0?


Si tu software est siendo usado en produccin, probablemente ya deberas estar en 1.0.0. SI tienes una
API estable de la cual tus usuarios ya estn dependiendo, deberas estar en 1.0.0. Si te preocupa mucho
la compatibilidad con versiones anteriores, ya deberas estar en 1.0.0.

Esto no desincentiva el desarrollo rpido y las iteraciones cortas?


La versin major en cero se trata de desarrollo rpido. Si ests cambiando la API todos los das debieras o
bien estar todava en la versin 0.y.z o estar trabajando en un branch separado para la prxima versin
major.

Si incluso el cambio incompatible con la versin anterior ms pequeo requiere un aumento de la


versin major No voy a terminar en la versin 42.0.0 demasiado rpido?
Este es un tema de desarrollo responsable y visin anticipada. Los cambios incompatibles no debieran ser
introducidos con ligereza al software del cual depende mucho cdigo. El costo de actualizar puede ser
significante. Tener que aumentar la versin major para publicar cambios incompatibles significa que vas a
pensar bien el efecto de tus cambios, y evaluar el costo/beneficio asociado.

Documentar la API pblica entera es demasiado trabajo!


Es tu responsabilidad como desarrollador profesional documentar adecuadamente el software pensado
para que lo usen otros. Gestionar la complejidad del software es una parte tremendamente importante de

mantener un proyecto eficiente, y es muy dificil de lograr si nadie sabe cmo usar tu software o qu
mtodos es seguro llamar. A largo plazo, el Versionamiento Semntico, y la insistencia en una API pblica
bien definida pueden asegurar que todos y todo corra de manera suave.

Qu hago si accidentalmente publico un cambio incompatible con la versin anterior como un


cambio de versin minor?
Apenas te des cuenta de que rompiste con la especificacin de Versionamiento Semntico, repara el
problema y publica una nueva versin minor que corrige el problema y recupera la compatiblidad. Incluso
en esta circunstancia, es inaceptable modificar releases versionados. Si corresponde, documenta la
versin que rompe la especificacin e informa a tus usuarios que estn atentos a ella.

Qu debera hacer si actualizo mis propias dependencias sin cambiar la API pblica?
Eso sera considerado compatible ya que no afecta al API pblica. El software que explcitamente depende
de las mismas dependencias que tu paquete debiera tener sus propias especificaciones de dependencia y
el autor va a notar cualquier conflicto. La determinacin de si el cambio es a nivel de patch o minor
depende de si actualizaste tus dependencias para arreglar un bug o para agregar funcionalidad nueva. Yo
esperara que haya cdigo adicional si se trata de lo segundo, en cuyo caso el incremento del minor es la
opcin obvia.

Qu debera hacer si el bug que estoy arreglando justamente hace que vuelva a estar de acuerdo
con la especificacin del API pblica? (es decir, el cdigo estaba incorrectamente desincronizado
con la documentacin del API)
Usa tu sentido comn. Si tienes una gran audiencia que se va a ver drsticamente afectada al cambiar el
comportamiento a lo que la API pblica deba hacer, entonces lo mejor puede ser hacer un release major,
incluso si el arreglo es estrictamente un release de tipo patch. Recuerda, el Versionamiento Semntico se
trata de incorporar significado a la forma en que el nmero de versin cambia. Si estos cambios son
importantes para tus usuarios, usa el nmero de versin para informarlos.

Cmo debiera controlar la funcionalidad deprecada?


Deprecar (desaprobar) funcionalidad existente es una parte normal del desarrollo de software y es
tpicamente requerida para avanzar. Cuando desapruebas parte de tu API pblica, deberas hacer dos
cosas: (1) actualizar tu documentacin para permitir que los usuarios sepan del cambio, (2) emitir un
nuevo release minor con la desaprobacin. Antes de sacar la funcionalidad por completo en un nuevo
release major, debera haber al menos un release minor que contenga la desaprobacin de manera tal que
los usuarios puedan traspasarse a la nueva API de manera suave.

Acerca de
La especificacin de Versionamiento Semntico fue creada por Tom Preston-Werner, inventor de los
Gravatars y co-fundador de GitHub. Esta traduccin fue realizada por Agustin Feuerhake.
Si quieres dar feedback, puedes abrir un issue en GitHub.

También podría gustarte