Conventional commits
Este post se ha creado a partir del vídeo de Carlos Azaustre, solo que como él explica cómo hacer todo con herramientas de JavaScript, hay mucha gente desarrolladora de Python que no tiene instalado Node.js, por lo que he hecho una versión del mismo pero todo con herramientas de Python.
¿Qué son los conventional commits?
la integración con herramientas de gestión de cambios y releases.
Formato de los Mensajes de Commit
Un mensaje de commit en Conventional Commits sigue un formato específico:
git
<type>[optional scope]: <description>
[optional body]
[optional footer(s)]Vamos a verlo más detalladamente
Tipo type
El tipo de commit indica la naturaleza del cambio. Algunos tipos comunes son:
- fix: Se utiliza para corrección de bugs.* feat: Se utiliza para nuevas funcionalidades. * docs: Se utiliza para cambios en la documentación.
- style: Se utiliza para cambios que no afectan el significado del código (por ejemplo, formato, eliminación de espacios en blanco). * refactor: Se utiliza para cambios de código que ni mejoran ni empeoran la funcionalidad, como reorganizar el código.
- perf: Se utiliza para cambios que mejoran el rendimiento.
- test: Se utiliza para agregar o actualizar pruebas. * chore: Se utiliza para cambios en el proceso o en las herramientas de desarrollo.
- ci: Se utiliza para cambios en los archivos de configuración de integración continua. * build: Se utiliza para cambios que afectan el sistema de compilación o dependencias externas.
- revert: Se utiliza para revertir un commit anterior.
Ámbito scope
El ámbito es opcional y se utiliza para especificar la parte del proyecto que se modificó. Por ejemplo, si estás trabajando en un componente específico de una aplicación web, el ámbito podría ser el nombre del componente.
Ejemplo:
git
fix(auth): fix authentication issueDescripción description
La descripción es una breve explicación del cambio. Debe ser concisa y clara, y proporcionar suficiente contexto para entender el propósito del commit.
Ejemplo:
git
fix(auth): fix authentication error on login pageCuerpo body
El cuerpo es opcional y se utiliza para proporcionar más detalles sobre el cambio. Aquí puedes incluir motivaciones para el cambio y contrastes con la implementación anterior.
Ejemplo:
git
fix(auth): fix authentication error on login page
The access token was expiring earlier than expected due to an error in the expiration date calculation. It has been fixed by adjusting the calculation logic.Pie de página footer
El pie de página es opcional y se utiliza para referencias adicionales, como números de issues cerrados o commits relacionados.
Ejemplo:
git
fix(auth): fix authentication error on login page
The access token was expiring earlier than expected due to an error in the expiration date calculation. It has been fixed by adjusting the calculation logic.
Closes #123Beneficios de los Conventional Commits
- Claridad y Consistencia: Los mensajes de commit estandarizados son más fáciles de entender y seguir, lo que mejora la colaboración en equipos de desarrollo. * Generación Automática de Notas de Versión: Se pueden usar herramientas para generar notas de versión automáticamente basándose en los mensajes de commit.
- Integración con Herramientas de Gestión de Cambios: Muchas herramientas de desarrollo y gestión de proyectos pueden integrarse con Conventional Commits para automatizar tareas como la generación de changelogs y la gestión de releases. * Historial de Cambios Estructurado: El historial de cambios se vuelve más estructurado y fácil de navegar, lo que facilita la revisión de cambios y la depuración de problemas.
Ejemplos prácticos
Ejemplo 1: Corrección de un Bug
git
fix(api): fix error in user validation
The user registration endpoint was allowing registrations with invalid email addresses. An additional validation has been added to ensure that email addresses are valid.
Closes #456Ejemplo 2: Añadir una Nueva Característica
git
feat(api): add password recovery endpoint
Implemented a new endpoint that allows users to request a password recovery link. The link is sent to their registered email address.
Closes #789Ejemplo 3: Mejora de la documentación
git
docs: update contribution guide
Updated the setup instructions for the development environment and added a section on running tests.
Closes #101Herramientas para construir mensajes que cumplan conventional commits
Aunque hemos visto cómo crear mensajes de commit mediante conventional commits, es bastante posible que nos equivoquemos, por lo que podemos usar herramientas que nos guíen en la creación de estos mensajes. Vamos a ver dos commitizen y el plugin Conventional Commit de vscode.
Commitizen
Para usarla, primero voy a crear una carpeta nueva en la que voy a iniciar un repositorio de Git
!mkdir ~/comitizen_folder && cd ~/comitizen_folder && git init
hint: Using 'master' as the name for the initial branch. This default branch namehint: is subject to change. To configure the initial branch name to use in allhint: of your new repositories, which will suppress this warning, call:hint:hint: git config --global init.defaultBranch <name>hint:hint: Names commonly chosen instead of 'master' are 'main', 'trunk' andhint: 'development'. The just-created branch can be renamed via this command:hint:hint: git branch -m <name>Initialized empty Git repository in /home/maximofernandez/comitizen_folder/.git/
Ahora instalo commitizen
%pip install --user -U commitizen
Collecting commitizenDownloading commitizen-3.29.1-py3-none-any.whl.metadata (7.6 kB)Collecting argcomplete<3.6,>=1.12.1 (from commitizen)Downloading argcomplete-3.5.1-py3-none-any.whl.metadata (16 kB)Requirement already satisfied: charset-normalizer<4,>=2.1.0 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from commitizen) (3.3.2)Requirement already satisfied: colorama<0.5.0,>=0.4.1 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from commitizen) (0.4.6)Collecting decli<0.7.0,>=0.6.0 (from commitizen)Downloading decli-0.6.2-py3-none-any.whl.metadata (17 kB)Requirement already satisfied: jinja2>=2.10.3 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from commitizen) (3.1.4)Requirement already satisfied: packaging>=19 in /home/maximofernandez/.local/lib/python3.12/site-packages (from commitizen) (24.1)Requirement already satisfied: pyyaml>=3.08 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from commitizen) (6.0.2)Collecting questionary<3.0,>=2.0 (from commitizen)Downloading questionary-2.0.1-py3-none-any.whl.metadata (5.4 kB)Collecting termcolor<3,>=1.1 (from commitizen)Downloading termcolor-2.5.0-py3-none-any.whl.metadata (6.1 kB)Collecting tomlkit<1.0.0,>=0.5.3 (from commitizen)Downloading tomlkit-0.13.2-py3-none-any.whl.metadata (2.7 kB)Requirement already satisfied: MarkupSafe>=2.0 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from jinja2>=2.10.3->commitizen) (2.1.5)Collecting prompt_toolkit<=3.0.36,>=2.0 (from questionary<3.0,>=2.0->commitizen)Downloading prompt_toolkit-3.0.36-py3-none-any.whl.metadata (7.0 kB)Requirement already satisfied: wcwidth in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from prompt_toolkit<=3.0.36,>=2.0->questionary<3.0,>=2.0->commitizen) (0.2.13)Downloading commitizen-3.29.1-py3-none-any.whl (71 kB)Downloading argcomplete-3.5.1-py3-none-any.whl (43 kB)Downloading decli-0.6.2-py3-none-any.whl (7.9 kB)Downloading questionary-2.0.1-py3-none-any.whl (34 kB)Downloading termcolor-2.5.0-py3-none-any.whl (7.8 kB)Downloading tomlkit-0.13.2-py3-none-any.whl (37 kB)Downloading prompt_toolkit-3.0.36-py3-none-any.whl (386 kB)Installing collected packages: tomlkit, termcolor, prompt_toolkit, decli, argcomplete, questionary, commitizenERROR: pip's dependency resolver does not currently take into account all the packages that are installed. This behaviour is the source of the following dependency conflicts.ipython 8.27.0 requires prompt-toolkit<3.1.0,>=3.0.41, but you have prompt-toolkit 3.0.36 which is incompatible.Successfully installed argcomplete-3.5.1 commitizen-3.29.1 decli-0.6.2 prompt_toolkit-3.0.36 questionary-2.0.1 termcolor-2.5.0 tomlkit-0.13.2Note: you may need to restart the kernel to use updated packages.
Verificamos la instalación
!cz version
3.29.1
Creo un nuevo archivo en la carpeta en la que he inicializado el repositorio de git y lo añado al área de staging
!cd ~/comitizen_folder && touch README.md && git add README.md
Si hago git status veré que el archivo está en el área de staging y que ahora debería hacer un commit
!cd ~/comitizen_folder && touch README.md && git add README.md!cd ~/comitizen_folder && git status
On branch masterNo commits yetChanges to be committed:(use "git rm --cached <file>..." to unstage)new file: README.md
Es hora de crear un commit con commitizen, para ello ejecutamos cz commit y nos aparecerá un asistente para crear el commit
!cd ~/comitizen_folder && cz commit
? Select the type of change you are committing docs: Documentation only changes? What is the scope of this change? (class or file name): (press [enter] to skip)readme? Write a short and imperative summary of the code changes: (lower case and no period)First innit, create readme? Provide additional contextual information about the code changes: (press [enter] to skip)This is the first commit, I create a empty readme? Is this a BREAKING CHANGE? Correlates with MAJOR in SemVer No? Footer. Information about Breaking Changes and reference issues that this commit closes: (press [enter] to skip)docs(readme): First innit, create readmeThis is the first commit, I create a empty readme[master (root-commit) 4f646d4] docs(readme): First innit, create readme1 file changed, 0 insertions(+), 0 deletions(-)create mode 100644 README.mdCommit successful!
Listo, ya tenemos nuestro primer commit creado con commitizen que sigue las reglas de Conventional Commits
Plugin Conventional Commit de vscode
Ahora vamos a hacer lo mismo solo que con el plugin de vscode Conventional Commit
Primero hay que instalar el plugin y una vez esté instalado pulsamos Ctrl + Shift + P y escribimos Conventional Commit, le damos a enter y nos aparecerá un asistente para crear el commit
Para mí el uso de este plugin tiene dos ventajas sobre commitizen
- La primera es que nos permite añadir emojis de gitmoji. Lo cual, si no se abusa de los emojis y se usan unos pocos, hace que al ver el historial de commits sea más fácil identificar el tipo de commit* La segunda es que guarda los ámbitos
scopes que has usado, por lo que hace que no se creen nuevos ámbitos sino que se reutilicen los que ya has usado
Herramientas para comprobar que se sigue la convención de conventional commits
Hemos visto cómo crear mensajes de commit que sigan la convención de conventional commits, pero una buena práctica es crear una herramienta para comprobar que el commit creado sigue la convención, sobre todo cuando se trabaja en equipo.
Hay herramientas que nos permiten hacer esto como pre-commit, pero lo que hacen es modificar los hooks de git, así que vamos a hacerlo nosotros y a usar commitizen para que nos ayude a validar el mensaje de commit.
Ya hemos instalado commitizen, así que vamos a ver cómo se puede usar para comprobar un mensaje de commit
Primero creamos un archivo llamado commit-msg en la carpeta .git/hooks y le damos permisos de ejecución. Dentro de los hooks de Git hay varios tipos de archivos que se pueden usar para diferentes tareas, en este caso vamos a usar commit-msg que se ejecuta justo antes de que se cree el commit.
!cd ~/comitizen_folder/.git/hooks && touch commit-msg && chmod +x commit-msg
Ahora añadimos el siguiente código al archivo commit-msg
#!/bin/sh
Este script valida el mensaje del commit usando commitizen
COMMIT_MSG_FILE=$1
cz check --commit-msg-file $COMMIT_MSG_FILE
!cd ~/comitizen_folder/.git/hooks && touch commit-msg && chmod +x commit-msg!cd ~/comitizen_folder/.git/hooks &&echo '#!/bin/sh' > commit-msg && \echo '# Este script valida el mensaje del commit usando commitizen' >> commit-msg && \echo ' ' >> commit-msg && \echo 'COMMIT_MSG_FILE=$1' >> commit-msg && \echo 'cz check --commit-msg-file $COMMIT_MSG_FILE' >> commit-msg
Una vez hecho probamos a hacer un commit con un mensaje incorrecto. Primero modificamos el readme y lo añadimos al área de staging
!cd ~/comitizen_folder/.git/hooks && touch commit-msg && chmod +x commit-msg!cd ~/comitizen_folder/.git/hooks &&echo '#!/bin/sh' > commit-msg && \echo '# Este script valida el mensaje del commit usando commitizen' >> commit-msg && \echo ' ' >> commit-msg && \echo 'COMMIT_MSG_FILE=$1' >> commit-msg && \echo 'cz check --commit-msg-file $COMMIT_MSG_FILE' >> commit-msg!cd ~/comitizen_folder && echo '.' >> README.md && git add README.md
Ahora hacemos un commit con un mensaje incorrecto
!cd ~/comitizen_folder/.git/hooks && touch commit-msg && chmod +x commit-msg!cd ~/comitizen_folder/.git/hooks &&echo '#!/bin/sh' > commit-msg && \echo '# Este script valida el mensaje del commit usando commitizen' >> commit-msg && \echo ' ' >> commit-msg && \echo 'COMMIT_MSG_FILE=$1' >> commit-msg && \echo 'cz check --commit-msg-file $COMMIT_MSG_FILE' >> commit-msg!cd ~/comitizen_folder && echo '.' >> README.md && git add README.md!cd ~/comitizen_folder && git commit -m "Add dot to README"
commit validation: failed!please enter a commit message in the commitizen format.commit "": "Add dot to README"pattern: (?s)(build|ci|docs|feat|fix|perf|refactor|style|test|chore|revert|bump)((S+))?!?:( [^ ]+)(( .*)|(s*))?$
Ahora hacemos un commit con un mensaje correcto
!cd ~/comitizen_folder && git commit -m "docs(readme): :memo: Add dot to README"
Commit validation: successful![master d488656] docs(readme): :memo: Add dot to README1 file changed, 1 insertion(+), 1 deletion(-)
Nos ha validado el commit correctamente, por lo que si miramos el historial de commits, veremos que el commit con el mensaje incorrecto no se ha creado y el commit con el mensaje correcto sí
!cd ~/comitizen_folder && git log
commit d488656297c7cb448a25dd33a008cb5ce1e14e83 (HEAD -> master)Author: MaximoFN <maximofn@gmail.com>Date: Tue Oct 8 11:22:19 2024 +0200docs(readme): :memo: Add dot to READMEcommit fb518c2b903a259b2e44972e88aabf5656f97be9Author: MaximoFN <maximofn@gmail.com>Date: Tue Oct 8 10:57:41 2024 +0200docs(readme): :memo: Update readmeUpdate readme with text conventional commitscommit 4f646d45047a45b549243efbfde9e331d45e23f1Author: MaximoFN <maximofn@gmail.com>Date: Tue Oct 8 10:48:07 2024 +0200docs(readme): First innit, create readmeThis is the first commit, I create a empty readme
Herramientas para crear changelogs a partir de conventional commits
Como tenemos los commits escritos mediante el mismo convenio, podemos crear changelog automáticamente con git-changelog. Instalamos las dependencias
%pip install git-changelog
Collecting git-changelogDownloading git_changelog-2.5.2-py3-none-any.whl.metadata (5.4 kB)Collecting appdirs>=1.4 (from git-changelog)Downloading appdirs-1.4.4-py2.py3-none-any.whl.metadata (9.0 kB)Requirement already satisfied: Jinja2>=2.10 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from git-changelog) (3.1.4)Requirement already satisfied: packaging>=24.0 in /home/maximofernandez/.local/lib/python3.12/site-packages (from git-changelog) (24.1)Collecting semver>=2.13 (from git-changelog)Downloading semver-3.0.2-py3-none-any.whl.metadata (5.0 kB)Requirement already satisfied: MarkupSafe>=2.0 in /home/maximofernandez/miniforge3/lib/python3.12/site-packages (from Jinja2>=2.10->git-changelog) (2.1.5)Downloading git_changelog-2.5.2-py3-none-any.whl (32 kB)Downloading appdirs-1.4.4-py2.py3-none-any.whl (9.6 kB)Downloading semver-3.0.2-py3-none-any.whl (17 kB)Installing collected packages: appdirs, semver, git-changelogSuccessfully installed appdirs-1.4.4 git-changelog-2.5.2 semver-3.0.2Note: you may need to restart the kernel to use updated packages.
Ahora podemos crear un changelog con git-changelog. Como hemos creado unos commits muy simples, el changelog será muy simple
!cd ~/comitizen_folder && git-changelog
# ChangelogAll notable changes to this project will be documented in this file.The format is based on [Keep a Changelog](http://keepachangelog.com/en/1.0.0/)and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.html).<!-- insertion marker -->## Unreleased<small>[Compare with latest]()</small><!-- insertion marker -->
También podemos pedirle que lo escriba en un archivo y muchas más opciones
!git-changelog -h
usage: git-changelog [--config-file [PATH ...]] [-b] [-B VERSION] [-n SCHEME][-h] [-i] [-g REGEX] [-m MARKER] [-o FILE] [-p PROVIDER][-r] [-R] [-I FILE] [-c CONVENTION] [-s SECTIONS][-t TEMPLATE] [-T] [-E] [-Z] [-F RANGE] [-j KEY=VALUE][-V] [--debug-info][REPOSITORY]Automatic Changelog generator using Jinja2 templates.This tool parses your commit messages to extract useful datathat is then rendered using Jinja2 templates, for example toa changelog file formatted in Markdown.Each Git tag will be treated as a version of your project.Each version contains a set of commits, and will be an entryin your changelog. Commits in each version will be groupedby sections, depending on the commit convention you follow.### Conventions#### Basic*Default sections:*- add: Added- fix: Fixed- change: Changed- remove: Removed*Additional sections:*- merge: Merged- doc: Documented#### Angular*Default sections:*- feat: Features- fix: Bug Fixes- revert: Reverts- ref, refactor: Code Refactoring- perf: Performance Improvements*Additional sections:*- build: Build- chore: Chore- ci: Continuous Integration- deps: Dependencies- doc, docs: Docs- style: Style- test, tests: Tests#### ConventionalCommit*Default sections:*- feat: Features- fix: Bug Fixes- revert: Reverts- ref, refactor: Code Refactoring- perf: Performance Improvements*Additional sections:*- build: Build- chore: Chore- ci: Continuous Integration- deps: Dependencies- doc, docs: Docs- style: Style- test, tests: Testspositional arguments:REPOSITORY The repository path, relative or absolute. Default:current working directory.options:--config-file [PATH ...]Configuration file(s).-b, --bump-latest Deprecated, use --bump=auto instead. Guess the newlatest version by bumping the previous one based onthe set of unreleased commits. For example, if acommit contains breaking changes, bump the majornumber (or the minor number for 0.x versions). Else ifthere are new features, bump the minor number. Elsejust bump the patch number. Default: unset (false).-B VERSION, --bump VERSIONSpecify the bump from latest version for the set ofunreleased commits. Can be one of `auto`, `major`,`minor`, `patch` or a valid SemVer version (eg.1.2.3). For both SemVer and PEP 440 versioning schemes(see -n), `auto` will bump the major number if acommit contains breaking changes (or the minor numberfor 0.x versions, see -Z), else the minor number ifthere are new features, else the patch number.Default: unset (false).-n SCHEME, --versioning SCHEMEVersioning scheme to use when bumping and comparingversions. The selected scheme will impact the valuesaccepted by the `--bump` option. Supported: `pep440`,`semver`. PEP 440 provides the following bumpstrategies: `auto`, `epoch`, `release`, `major`,`minor`, `micro`, `patch`, `pre`, `alpha`, `beta`,`candidate`, `post`, `dev`. Values `auto`, `major`,`minor`, `micro` can be suffixed with one of `+alpha`,`+beta`, `+candidate`, and/or `+dev`. Values `alpha`,`beta` and `candidate` can be suffixed with `+dev`.Examples: `auto+alpha`, `major+beta+dev`, `micro+dev`,`candidate+dev`, etc.. SemVer provides the followingbump strategies: `auto`, `major`, `minor`, `patch`,`release`. See the docs for more information. Default:unset (`semver`).-h, --help Show this help message and exit.-i, --in-place Insert new entries (versions missing from changelog)in-place. An output file must be specified. Withcustom templates, you can pass two additionalarguments: `--version-regex` and `--marker-line`. Whenwriting in-place, an `in_place` variable will beinjected in the Jinja context, allowing to adapt thegenerated contents (for example to skip changelogheaders or footers). Default: unset (false).-g REGEX, --version-regex REGEXA regular expression to match versions in the existingchangelog (used to find the latest release) whenwriting in-place. The regular expression must be aPython regex with a `version` named group. Default:`^## [(?P<version>v?[^]]+)`.-m MARKER, --marker-line MARKERA marker line at which to insert new entries (versionsmissing from changelog). If two marker lines arepresent in the changelog, the contents between thosetwo lines will be overwritten (useful to update an'Unreleased' entry for example). Default: `<!--insertion marker -->`.-o FILE, --output FILEOutput to given file. Default: standard output.-p PROVIDER, --provider PROVIDERExplicitly specify the repository provider. Default:unset.-r, --parse-refs Parse provider-specific references in commit messages(GitHub/GitLab/Bitbucket issues, PRs, etc.). Default:unset (false).-R, --release-notes Output release notes to stdout based on the last entryin the changelog. Default: unset (false).-I FILE, --input FILERead from given file when creating release notes.Default: `CHANGELOG.md`.-c CONVENTION, --convention CONVENTION, --commit-style CONVENTION, --style CONVENTIONThe commit convention to match against. Default:`basic`.-s SECTIONS, --sections SECTIONSA comma-separated list of sections to render. See theavailable sections for each supported convention inthe description. Default: unset (None).-t TEMPLATE, --template TEMPLATEThe Jinja2 template to use. Prefix it with `path:` tospecify the path to a Jinja templated file. Default:`keepachangelog`.-T, --trailers, --git-trailersParse Git trailers in the commit message. Seehttps://git-scm.com/docs/git-interpret-trailers.Default: unset (false).-E, --omit-empty-versionsOmit empty versions from the output. Default: unset(false).-Z, --no-zerover By default, breaking changes on a 0.x don't bump themajor version, maintaining it at 0. With this option,a breaking change will bump a 0.x version to 1.0.-F RANGE, --filter-commits RANGEThe Git revision-range filter to use (e.g.`v1.2.0..`). Default: no filter.-j KEY=VALUE, --jinja-context KEY=VALUEPass additional key/value pairs to the template.Option can be used multiple times. The key/value pairsare accessible as 'jinja_context' in the template.-V, --version Show the current version of the program and exit.--debug-info Print debug information.
Ya podríamos generar changelogs fácilmente a partir de los commits que siguen la convención de conventional commits. Además, podemos añadirlo a un pipeline de CI/CD para que se genere automáticamente en cada release.
