Documentos de Académico
Documentos de Profesional
Documentos de Cultura
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.
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.
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.
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 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.
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.