Convención de commits

Definición

La convención de commits es una manera sencilla de organizar los mensajes que establecen los programadores en los commits. Contiene un sencillo conjunto de reglas para crear una historia explicita de commits. Esta convención está unido a SemVer, describiendo features, fixes y breaking changes hechos en los mensajes del commit.

¿Por qué usar la convención de commits?

Automáticamente genera CHANGELOGs.
Determinar automáticamente un aumento de versión semántica.
Comunica la naturaleza de los cambios a los compañeros de equipo, al público y a otras partes interesadas.
Activación de procesos de compilación y publicación.
Facilitar que las personas contribuyan a sus proyectos, permitiéndoles explorar un historial de commits más estructurado.

Versionado semántico

MAJOR version cuando haces incompatible los cambios de la API.
MINOR version cuando añades funcionalidad de manera compatible.
PATCH version cuando realiza correcciones de errores compatibles con versiones anteriores.

Estructura

fix: un commit de tipo fix corrige un error en la base del código. En el versionado semántico estaría relacionado con el termino PATCH.
feat: introduce una nueva funcionalidad. En el versionado semántico se establecería con MINOR.
BREAKING CHANGE: un commit que contiene la nota al pie BREAKING CHANGE: , o que agrega un ! después del tipo/ámbito, introduce un cambio de ruptura de API. Un BREAKING CHANGE puede ser parte de commits de cualquier tipo. Se relaciona con MAJOR en el versionado semantico.
Tipos distintos a fix: y feat: están permitidos (basados en Angular, @commitlint/config-conventional). Otros pueden ser build: , chore: , cli: , docs: , style: , refactor: , perf: , test: , y otros.
Notas al pie distintas de BREAKING CHANGE: <description> pueden ser añadidas y siguen una convención similar al formato git trailer.

Ejemplos

Mensaje de commit con descripción y cambio de ruptura en la nota al pie

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

Mensaje de commit con ! para llamar la atención al cambio de ruptura

refactor!: drop support for Node 6

Mensaje de commit con ambos ! y BREAKING CHANGE en la nota al pie

refactor!: drop support for Node 6

BREAKING CHANGE: refactor to use JavaScript features not available in Node 6.

Mensaje de commit sin cuerpo

docs: correct spelling of CHANGELOG

Mensaje de commit con ámbito

feat(lang): added polish language

Mensaje de commit con cuerpo multi-párrafo y múltiples notas al pie

fix: correct minor typos in code

see the issue for details

on typos fixed.

Reviewed-by: Z
Refs #133

Especificación

Los commits DEBEN iniciarse con un prefijo de tipo que consiste en un sustantivo, feat, fix, etc., seguido del ámbito OPCIONAL, !OPCIONAL, y dos puntos y un espacio REQUERIDO.
El tipo feat DEBE ser usado cuando un commit agrega una nueva funcionalidad a la aplicación o librería.
El tipo fix DEBE ser usado cuando el commit representa una corrección a un error en el código de la aplicación (bug).
Un ámbito PUEDE ser añadido después de un tipo. Un ámbito DEBE consistir en un sustantivo que describa una sección de la base del código encerrado entre paréntesis, ej., fix(parser):.
Una descripción DEBE ir inmediatamente después de los dos puntos y el espacio del prefijo de tipo/ámbito. La descripción es resúmen corto de los cambios realizados en el código, ej., fix: array parsing issue when multiple spaces were contained in string..
Un cuerpo de commit más extenso PUEDE agregarse después de la descripción corta, dando información contextual adicional acerca de los cambios en el código. El cuerpo DEBE iniciar después de una línea en blanco después de la descripción.
Un cuerpo de commit es de forma-libre y PUEDE consistir de cualquier número de párrafos separados por una nueva línea.
Una o más notas al pie PUEDEN ser añadidas una línea en blanco después del cuerpo. Cada nota al pie DEBE consistir de una palabra clave, seguida ya sea por un separador :<espacio> o <espacio>#, seguido por un valor cadena (string) (esto está inspirado por la convención git trailer).
Una palabra clave de una nota al pie DEBE usar - en lugar de caracteres de espacios en blanco, ej., Acked-by (esto ayuda a diferenciar la sección de la nota al pie de un cuerpo multi párrafo). Se hace una excepción para BREAKING CHANGE, que también PUEDE ser usada como palabra clave.
Una nota al pie PUEDE contener espacios y líneas en blanco, y el parseo DEBE terminar cuando se observe el siguiente separador/clave.
Los cambios de ruptura DEBEN ser indicados en el prefijo de tipo/ámbito de un commit, o como una entrada en la nota al pie.
Si se incluye como una nota al pie, un cambio de ruptura DEBE consistir del texto en mayúsculas BREAKING CHANGE, seguido de dos puntos, y una descripción, ej., BREAKING CHANGE: environment variables now take precedence over config files.
Si se incluye en el prefijo de tipo/ámbito, cambios de ruptura DEBEN ser indicados por un ! inmediatamente después de :. Si ! es usado, BREAKING CHANGE: PUEDE ser omitido de la sección de la nota al pie, y la descripción del commit DEBERÁ ser usada para describir el cambio de ruptura.
Tipos diferentes a feat y fix PUEDEN ser usados en los mensajes de commit, ej., docs: updated ref docs..
Las unidades de información que componen Commits Convencionales NO DEBEN ser tratados como implementadores sensitivos de caso, con la excepción de BREAKING CHANGE que DEBE ir en mayúsculas.
BREAKING-CHANGE DEBE ser sinónimo de BREAKING CHANGE, cuando se usa en una nota al pie.

Librerias

Existen varias librerias con las que puedes generar el fichero CHANGELOG.md de manera automática, estas son algunas del repositorio de Node Package Manager:

Standard-version

Changelog

conventional-changelog - npm (npmjs.com)

Repositorio

En este repositorio encontrareis un proyecto Angular con la librería Standard-version y un ejemplo de generación de Changelog.

CousiGoico/AngularChangeLog

Referencias

Conventional commits

Semantic Versioning