Creación de nuevas versiones de su paquete de Python#
Principal conclusiones
Siga las reglas de directrices de versionado semántico (SemVer) cuando aumente la versión de su paquete de Python; por ejemplo, un aumento de versión mayor (versión 1.0 –> 2.0) equivale a cambios que rompen el código de su paquete para un usuario.
Es posible que desee considerar el uso de un plugin como hatch_vsc para gestionar las versiones de su paquete, si desea tener un flujo de trabajo de versionado solo en GitHub.
De lo contrario, la mayoría de las principales herramientas de construcción de paquetes, como Hatch, Flit y PDM, tienen una función de versión que le ayudará a actualizar la versión de su paquete.
Evite actualizar manualmente el número de versión de sus paquetes en su código!
pyOpenSci recomienda que siga el PEP 440 de Python que recomienda el uso de directrices de versionado semántico al crear nuevas versiones de su paquete de Python.
El versionado semántico es un enfoque para actualizar las versiones de los paquetes que depende del tipo y la extensión del cambio que está realizando en el código del paquete. Ser coherente con cómo y cuándo actualiza las versiones de su paquete es importante ya que:
Ayuda a sus usuarios (que pueden incluir a otros desarrolladores que dependen de su paquete) a comprender la extensión de los cambios en un paquete.
Ayuda a su equipo de desarrollo a tomar decisiones sobre cuándo aumentar una versión de paquete basándose en reglas estándar.
Consistent version increases following semver rules mean that values of your package version explain the extent of the changes made in the code base from version to version. Thus your package version numbers become «expressive» in the same way that naming code variables well can make code expressive.
Una nota sobre el versionado
En algunos casos, incluso pequeños cambios de versión pueden convertir una actualización de paquete en un cambio que rompe para algunos usuarios. Por lo tanto es importante es que documente cómo versiona su código y, si puede, también la política de deprecación para el código.
Reglas de SemVer#
Siguiendo SemVer, aumente la versión de su paquete a:
patch (1.1.1 –> 1.1.2)
minor (1.1.1 –> 1.2.1)
major (1.1.1 –> 2.1.1)
El cambio de número de versión se basa en las siguientes reglas:
Dado un número de versión MAJOR.MINOR.PATCH, incremente:
Versión MAJOR cuando realice cambios incompatibles en la API
Versión MINOR cuando agregue funcionalidad de manera compatible con versiones anteriores
Versión PATCH cuando realice correcciones de errores compatibles con versiones anteriores. Se encuentran disponibles etiquetas adicionales para metadatos de prelanzamiento y compilación como extensiones del formato MAJOR.MINOR.PATCH.
Nota
Algunas personas prefieren usar calver para el versionado. Puede ser un sistema más fácil de usar dado que se basa en valores de fecha asociados con las versiones lanzadas. Sin embargo, calver no proporciona al usuario una idea de cuándo una nueva versión podría romper una compilación existente. Por lo tanto, seguimos sugiriendo semver.
¡pyOpenSci nunca requerirá semver en una revisión por pares siempre que un paquete tenga un enfoque razonable para el versionado!
Evite actualizar manualmente los números de versión de los paquetes de Python si puede#
A menudo, es posible que desee tener el valor de la versión de su paquete en múltiples ubicaciones. Un ejemplo de esto es que podría ser tanto un atributo en su paquete version como también llamado en su documentación.
Recomendamos que evite las actualizaciones manuales del número de versión de su paquete para evitar errores humanos. Es mejor mantener su número de versión en una sola ubicación.
Si no puede implementar una versión de una sola ubicación, considere usar una herramienta como hatch, PDM o bump2version que actualizará los valores de versión por usted, en todo su paquete.
A continuación, discutimos algunas herramientas que puede utilizar para actualizar las versiones de los paquetes de Python.
Herramientas para gestionar versiones de su paquete de Python#
Hay un puñado de herramientas que se utilizan ampliamente en el ecosistema científico que puede utilizar para gestionar las versiones de su paquete. Algunas de estas herramientas están integradas o funcionan con las herramientas de construcción de paquetes que elija que se discuten en este capítulo.
A continuación, proporcionamos una descripción general de estas herramientas.
Hay tres grupos generales de herramientas que puede utilizar para gestionar las versiones de los paquetes:
herramientas de versionado semántico: Estas herramientas determinarán automáticamente qué tipo de aumento de versión usar utilizando el texto en los mensajes de confirmación o commits. A continuación, discutimos Python Semantic Release como una herramienta de Python que implementa un enfoque de versionado semántico.
Herramientas de aumento incremental manual: Herramientas como Hatch ofrecen el aumento de versión dentro de su paquete. Normalmente, esto se ejecuta en la línea de comandos, por ejemplo,
hatch version majoraumentaría su proyecto de 0.x a 1.0.Herramientas del sistema de control de versiones: Por último, hay herramientas que dependen de su sistema de control de versiones para seguir las versiones. Estas herramientas a menudo son complementos de su herramienta de construcción de paquetes (por ejemplo, construcción de setuptools o hatchling). Discutimos esta opción a continuación asumiendo que está utilizando etiquetas .git y GitHub para gestionar el repositorio de su paquete.
Publicación semántica, vs. basada en control de versiones vs. aumento manual de versiones#
Generally semantic release and version control system tools can be setup to run automatically on GitHub using GitHub Actions. This means that you can create a workflow where a GitHub release and associated new version tag is used to trigger an automated build that:
Construye su paquete y actualiza la versión siguiendo la nueva etiqueta
Prueba la compilación y publica en test PyPI
Publica el paquete en PyPI
Nota
Bumping a package version refers to the step of increasing the package version after a set number of changes have been made to it. For example, you might bump from version 0.8 to 0.9 of a package or from 0.9 to 1.0.
Usando el versionado semántico, hay tres «niveles» principales de versiones que podría considerar:
Mayor, menor y parche (del inglés major, minor y patch). Estos se describen con más detalle a continuación.
Herramientas para aumentar las versiones de los paquetes de Python#
En esta sección discutimos las siguientes herramientas para gestionar la versión de su paquete de Python:
hatch &
plugin hatch_vcs para hatchling
setuptools-scm
python-semantic-version
Heramienta 1: Hatch y otras herramientas de construcción que ofrecen versionado incremental#
Muchas de las herramientas de construcción modernas ofrecen soporte de versión que siguen las reglas de versionado semántico. Estas herramientas son diferentes de Python Semantic Version en que no requieren mensajes de confirmación específicos para implementar la versión. Más bien, le permiten actualizar la versión en la línea de comandos usando comandos como:
tool-name version update majortool-name version update minor
Hatch, por ejemplo, ofrece hatch version minor que modificará la versión de su paquete de forma incremental. Con Hatch, el valor de la versión se encontrará en su archivo pyproject.toml.
Hatch (or other tools like PDM) pros#
Fácil de usar actualizaciones de versión localmente usando una sola herramienta!
Hatch (or other tools like PDM) cons#
Habrá alguna configuración involucrada para asegurarse de que la versión del paquete se actualice en todo su paquete
Heramienta 2: Hatch_vcs & hatchling build backend#
hatch_vcs es una herramienta de versionado que le permite gestionar las versiones de los paquetes utilizando etiquetas git. Hatch_vcs crea un archivo _version.py en su ecosistema de paquetes que realiza un seguimiento de la versión actual del paquete.
Hatch realiza un seguimiento de la versión de su paquete en un archivo _version.py. Almacenar la versión en un solo archivo gestionado por Hatch proporciona a su paquete un valor de «única fuente de verdad» para el número de versión. Esto, a su vez, elimina el error potencial asociado con la actualización manual de la versión de su paquete.
When you (or your CI system) build your package, hatch checks the current tag number for your package. If it has increased, it will update the _version.py file with the new value.
Así, cuando cree una nueva etiqueta o una nueva versión con una etiqueta y construya su paquete, Hatch accederá al nuevo valor de la etiqueta y lo utilizará para actualizar la versión de su paquete.
Para usar hatch_vcs necesitará usar el backend de construcción hatchling.
Truco
Hatchling también se puede utilizar con cualquiera de las herramientas de construcción modernas, incluidas Flit y PDM, si prefiere esas para su flujo de trabajo diario.
Ejecución de ejemplo de Hatch en su pyproject.toml#
# pyproject.toml example build setup to use hatchling and hatch_vcs
[build-system]
requires = ["hatchling", "hatch-vcs"]
build-backend = "hatchling.build"
Hatch_vcs admite un flujo de trabajo de publicación y construcción de paquetes totalmente automatizado, y envío a PyPI en GitHub.
# Example hatch vcs setup in the pyproject.toml file
[tool.hatch.build.hooks.vcs]
version-file = "_version.py"
Truco
Si utiliza setuptools_scm, entonces podría encontrar que hatch_vcs y hatchling son el equivalente moderno a su flujo de trabajo actual de setuptools / buils.
hatch_vcs pros#
Hatch admite estándares modernos de empaquetado de Python
Permite crear un archivo de única fuente de verdad que contiene la versión de su paquete.
Nunca actualizará manualmente la versión del paquete
Puede automatizar la escritura de la versión en cualquier lugar de su paquete, incluida su documentación.
Admite un flujo de trabajo de publicación basado puramente en GitHub. Esto simplifica los flujos de trabajo de mantenimiento.
El número de versión se actualiza en su paquete a través de un archivo oculto
_version.py. No se requieren actualizaciones manuales de configuración.Si bien nos gustan los mensajes de commit detallados (consulte Python Semantic Version a continuación), sabemos que a veces, al mantener un paquete, las pautas específicas sobre los mensajes de commit pueden ser difíciles de aplicar y gestionar.
hatch_vcs cons#
En un flujo de trabajo de CI, terminará ingresando o creando manualmente el número de versión a través de una etiqueta en GitHub. Pero podría desarrollar localmente una compilación para «aumentar» las versiones de las etiquetas
Herramienta 4: Python semantic release#
Python semantic release utiliza un flujo de trabajo de mensajes de commit que actualiza la versión de su paquete basándose en palabras clave encontradas en sus mensajes de commit. Como su nombre lo indica, Python Semantic Release sigue las reglas de lanzamiento de semver.
Con Python Semantic Release, las versiones se activan utilizando un lenguaje específico que se encuentra en un mensaje de commit de git.
Por ejemplo, las palabras fix(attribute_warning): activan Python Semantic Release para implementar un aumento de versión de patch. Por ejemplo, si su paquete estaba en la versión 1.1.0 y realizó el commit a continuación con las palabras fix(text-here), Python Semantic Release aumentaría su paquete a la versión 1.1.1.
git commit -m "fix(mod_plotting): fix warnings returned athlete attributes"
De manera similar, una característica (feat()) activa un aumento de versión menor. Por ejemplo, de la versión 1.1 a la versión 1.2
git commit -m "feature(add_conversions): add value conversions to activity date"
Truco
Puede encontrar una discusión reflexiva sobre la versión semántica de Python en esta guía de paquetes de Python. ¡Tenga en cuenta que la guía no ha sido actualizada desde 2020 y potencialmente se actualizará en el futuro! Por ahora, algunos de los comandos están desactualizados, pero el contenido sigue siendo excelente.
Python Semantic Release pros#
Siguen de cerca el versionado semver
Obliga a los mantenedores a usar mensajes de commit descriptivos que pueden simplificar la solución de problemas y garantizar un historial de git más limpio y autoexplicativo.
Python Semantic Release cons#
Requiere un lenguaje de confirmación muy específico para funcionar. En la práctica, algunos mantenedores y colaboradores pueden no ser capaces de mantener ese nivel de especificidad en los mensajes de confirmación (NOTA: hay bots que verificarán los mensajes de confirmación de git en un repositorio)
La publicación se realiza en la línea de comandos. Esto hace que sea más complicado implementar un flujo de trabajo de publicación basado en GitHub, ya que un mensaje de confirmación incorrecto podría activar una publicación.
El número de versión se actualiza manualmente en un archivo de configuración como
pyproject.tomlen lugar de en un archivo de paquete _version.py.