Caos familiar en los nombres de commits. 驴Una foto familiar?Seguramente sabes
git-flow . Este es un gran conjunto de convenciones de ramificaci贸n en Git. Est谩 bien documentado y ampliamente distribuido. Por lo general, estamos familiarizados con la ramificaci贸n correcta y hablamos mucho al respecto, pero, desafortunadamente, prestamos muy poca atenci贸n al tema de las confirmaciones de nombres, por lo que los mensajes en Git a menudo se escriben de manera no sistem谩tica.
Mi nombre es Yerzhan Tashbenbetov, trabajo en uno de los equipos de Yandex.Market. Y hoy les dir茅 a los lectores de Habr qu茅 herramientas usamos para crear compromisos significativos en un equipo. Los invito a unirse a la discusi贸n sobre este tema.
La falta de acuerdo sobre los compromisos de nomenclatura hace que sea dif铆cil trabajar con la historia en Git. Esto estaba en nuestro equipo. Antes de usar reglas comunes para todos e implementar la automatizaci贸n, las confirmaciones t铆picas se ve铆an de la siguiente manera:
SECRETMRKT-700: , . SECRETMRKT-701, SECRETMRKT-702: ...
En primer lugar, cada desarrollador escribi贸 los mensajes que quer铆a: alguien describi贸 la tarea, alguien enumer贸 los cambios realizados, alguien utiliz贸 un generador de frases al azar. Todo estaba en desacuerdo. En segundo lugar, los n煤meros de tareas que estaban presentes en las confirmaciones a menudo acortaban el texto 煤til. Todo esto dificultaba trabajar de manera efectiva con la historia en Git.
Por esta raz贸n, implementamos el est谩ndar de
Comisiones Convencionales en el equipo, comenzamos a generar confirmaciones en la utilidad de consola y verificamos el resultado usando
commitlint . Como resultado, los commits han cambiado y se ven as铆:
refactor(tutorial): feat(products): fix(products):
Leer la historia y reconocer los cambios se hizo m谩s f谩cil. No nos negamos a especificar n煤meros de tareas; todo se movi贸 cuidadosamente a los compromisos de acuerdo con la
convenci贸n de Comit茅s Convencionales .
A continuaci贸n, le mostrar茅 c贸mo lograr un orden similar en Git.
Mejores pr谩cticas, recomendaciones y soluciones comunes para nombrar commits
Si intenta comprender qu茅 pr谩cticas se utilizan en la industria, puede encontrar las siguientes opciones:
- Art铆culos con consejos generales para escribir commits. En su mayor parte, son bastante l贸gicos y abren un buen tema, pero hay una sensaci贸n de desorden y falta de una soluci贸n integral al problema.
- Est谩ndares para escribir confirmaciones. Hay pocos de ellos. Son documentos con una lista clara de reglas, a menudo escritas espec铆ficamente para una gran biblioteca o marco. Estos est谩ndares impresionan con un enfoque sistem谩tico, popularidad y soporte en la comunidad de c贸digo abierto.
隆Necesitamos m谩s orden en commits!
La
metodolog铆a de los Comit茅s convencionales se destaca de otros est谩ndares y merece un examen minucioso por varias razones:
- Est谩 bien documentado y dise帽ado. Su especificaci贸n proporciona respuestas a las preguntas m谩s comunes.
- Los creadores de la convenci贸n se inspiraron en los requisitos para escribir confirmaciones, que se utilizan en el popular y probado marco AngularJS .
- Las reglas de la convenci贸n son seguidas por varias bibliotecas de c贸digo abierto grandes y populares (como yargs y lerna ).
- Adem谩s, har茅 los preparativos para la formaci贸n autom谩tica de las Notas de la versi贸n y el Registro de cambios.
Un ejemplo de compromiso con este est谩ndar: fix(products): - . : SECRETMRKT-578, SECRETMRKT-602
Puntos clave de los compromisos convencionales
- El desarrollador debe cumplir con la siguiente estructura de confirmaci贸n:
<tipo> (<scope>): <subject>
<cuerpo>
<footer>
- El commit debe tener un encabezado, tal vez un cuerpo y un pie de p谩gina.
- El encabezado de la confirmaci贸n debe comenzar con un tipo que indique los detalles de los cambios realizados en la base del c贸digo, y terminar con una descripci贸n.
- Junto con la proeza obligatoria, corregir (cuyo uso est谩 estrictamente regulado), se permiten otros tipos.
- Un commit puede tener un alcance . Caracteriza un fragmento de c贸digo que se ha visto afectado por los cambios. El 谩rea sigue el tipo de confirmaci贸n. La norma no regula una lista clara de 谩reas. Ejemplos de 谩reas: eslint, git, analytics, etc.
- La descripci贸n de confirmaci贸n debe aparecer inmediatamente despu茅s del tipo / 谩rea.
- El cuerpo de la confirmaci贸n se puede utilizar para profundizar en los cambios. El cuerpo debe estar separado de la descripci贸n por una l铆nea vac铆a.
- El pie de p谩gina debe usarse para especificar enlaces externos, el contexto de la confirmaci贸n u otra metainformaci贸n. El pie de p谩gina debe estar separado del cuerpo por una l铆nea vac铆a.
Adem谩s de las reglas enumeradas en la convenci贸n, utilizamos las siguientes recomendaciones populares:
- En el cuerpo del commit escribimos qu茅 ha cambiado y por qu茅 .
- Utilizamos los siguientes tipos de confirmaciones:
| construir | Cree un proyecto o cambie dependencias externas |
| ci | Configuraci贸n de CI y secuencias de comandos |
| docs | Actualizaci贸n de documentaci贸n |
| haza帽a | Agregar nueva funcionalidad |
| arreglar | Correcci贸n de errores |
| perf | Cambios de mejora del rendimiento |
| refactor | Edici贸n de c贸digo sin corregir errores o agregar nuevas funciones |
| revertir | Volver a las confirmaciones anteriores |
| estilo | Ediciones de estilo de c贸digo (pesta帽as, sangr铆as, puntos, comas, etc.) |
| prueba | Agregar pruebas |
- Escribimos la descripci贸n en un estado de 谩nimo imperativo , al igual que el propio Git.
Fusionar rama 'fix / SECRETMRKT-749-fix-typos-in-title'
- No cargue la descripci贸n de confirmaci贸n con signos de puntuaci贸n.
Est谩ndar de compromisos convencionales utilizado por los contribuyentes de lerna
驴C贸mo simplemente cambiar al nombre correcto de commits?
Necesita agregar automatizaci贸n y conveniencia. Para resolver este problema, necesitamos dos herramientas: el generador de confirmaci贸n y la hoja de confirmaci贸n, configurados para verificar antes de pasar al repositorio.
Configurar la utilidad de compromiso
Esta herramienta le permite generar confirmaciones utilizando el asistente incorporado. Adem谩s, commitizen cuenta con el apoyo de la comunidad y, gracias a los m贸dulos adicionales, es altamente personalizable.
- Instale la utilidad commitizen a nivel mundial (es posible que necesite derechos de administrador).
npm i -g commitizen
- A continuaci贸n, instale el adaptador personalizable cz . Es necesario configurar la plantilla con preguntas utilizadas por la utilidad commitizen .
npm i -D cz-customizable
- Creemos el archivo commitizen.js, es necesario configurar cz-customizable. Coloque el archivo creado en el directorio ./config/git. Recomiendo no llenar la ra铆z del proyecto con archivos de configuraci贸n e intentar agrupar los archivos en una carpeta preparada para esto. Contenido:
Mostrar commitizen.js "use strict"; module.exports = {
- Agregue enlaces a cz-personalizable y el archivo de configuraci贸n creado previamente en package.json:
Mostrar parte de package.json { "config": { "commitizen": { "path": "node_modules/cz-customizable" }, "cz-customizable": { "config": "config/git/commitizen.js" } }, }
- Veamos el resultado. Escriba el siguiente comando en la terminal:
git cz
El asistente de compromiso primero recopilar谩 informaci贸n sobre el tipo, el 谩rea del compromiso, luego solicitar谩 secuencialmente el texto que estar谩 en la descripci贸n, en el cuerpo, en el pie de p谩gina y, despu茅s de su consentimiento, crear谩 un compromiso.
Aseg煤rese de ver el ejemplo de la utilidad commitizen configurada y el adaptador cz-cusomizable conectado a ella
Configurar utilidades husky y commitlint
- Instale husky y commitlint en el proyecto:
npm i -D husky @commitlint/cli
- Con Husky, agregaremos una verificaci贸n de confirmaci贸n. Para hacer esto, en package.json, inmediatamente despu茅s de los scripts, agregue el siguiente enlace e indique en 茅l un enlace al archivo commitlint.js:
Mostrar parte de package.json { "scripts": { "test": "echo \"Error: no test specified\" && exit 1" }, "husky": { "hooks": { "commit-msg": "commitlint -E HUSKY_GIT_PARAMS -g './config/git/commitlint.js'" } }, "devDependencies": { "@commitlint/cli": "^7.2.1", "husky": "^1.1.3", }
- Cree el archivo commitlint.js necesario para que el linter funcione correctamente. Coloque el archivo creado en el directorio ./config/git. Contenido del archivo:
Eso es todo. Ahora se comprobar谩n todas las confirmaciones antes de enviarlas al repositorio :)
Aseg煤rese de ver el ejemplo de la utilidad commitlint configurada
Entonces, 驴qu茅 elegir commitizen o commitlint?
隆Tanto eso como otro! En conjunto, brindan excelentes resultados: el primero genera commits, el segundo los verifica.
驴Por qu茅 los est谩ndares recomiendan el uso de imperativo?
Esta es una pregunta extremadamente interesante. Un commit es un cambio de c贸digo; un mensaje en un commit puede considerarse como instrucciones para cambiar este c贸digo. Hacer, cambiar, agregar, actualizar, corregir: todas estas son instrucciones espec铆ficas para el desarrollador.
Por cierto, se recomienda imperativo en el
propio sistema de versiones de
Git :
[[imperative-mood]] Describe your changes in imperative mood, eg "make xyzzy do frotz" instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behavior.
驴Por qu茅 atenerse a alguna convenci贸n? 驴Vale la pena el tiempo? 驴Cu谩l es el beneficio?
Vale la pena En general, not茅 que est谩bamos m谩s dispuestos a detallar los cambios realizados en la base del c贸digo. En el cuerpo del commit, describimos en detalle por qu茅 tuvimos que usar estas o esas soluciones. Comprender la historia se ha vuelto objetivamente m谩s f谩cil. Adem谩s, nuestro producto se est谩 desarrollando y esperamos una reposici贸n en el equipo. Estoy seguro de que gracias a la introducci贸n del est谩ndar y la automatizaci贸n, ser谩 m谩s f谩cil para los principiantes integrarse en el proceso de desarrollo.
Intenta y comparte el resultado.
Enlaces utiles: