Cómo escribir buenos mensajes de compromiso: una guía práctica de Git

Para crear un historial de revisión útil, los equipos primero deben acordar una convención de mensajes de confirmación para usar. Esto también se aplica a los proyectos personales.

Recientemente en Hashnode pregunté, "¿Qué convención de mensajes de confirmación usas en el trabajo?" y obtuve algunas respuestas asombrosas con los usuarios que explican las convenciones que usan en el trabajo y para sus proyectos personales.

¿Qué convención de mensajes de confirmación usas en el trabajo?

de @hashnode //t.co/HewCBxRCbr

- BOLAJI ✨ (@iambolajiayo) 25 de noviembre de 2019

En este artículo, repasaré cómo escribir buenos mensajes de confirmación y por qué debería hacerlo.

PD: Este artículo se publicó por primera vez en mi blog aquí.

Introducción al control de versiones con Git

El software de control de versiones es una parte esencial de las prácticas modernas de desarrollo de software.

De lejos, Git es el sistema de control de versiones más utilizado en el mundo. Es un proyecto de código abierto distribuido y mantenido activamente desarrollado originalmente en 2005 por Linus Torvalds, el famoso creador del kernel del sistema operativo Linux.

¿Nuevo en Git? Consulte la guía oficial de introducción o esta diapositiva de una charla anterior que di.

¿Qué es un mensaje de confirmación?

El comando de confirmación se usa para guardar cambios en un repositorio local después de la preparación en Git. Sin embargo, antes de que pueda guardar cambios en Git, debe decirle a Git qué cambios desea guardar, ya que es posible que haya realizado toneladas de ediciones. Una excelente manera de hacerlo es agregando un mensaje de confirmación para identificar sus cambios.

Opciones de confirmación

  • -metro

Esta opción establece el mensaje de la confirmación.

git add static/admin/config.yml git commit -m "Setup multiple roles for netlify-cms git gateway" 
  • -a o --todos

Esta opción confirma automáticamente todos los archivos rastreados, modificados o eliminados (incluidos los nuevos).

git commit -a -m "Add a new role for netlify-cms git gateway" 
  • --enmendar

Esta opción reescribe la última confirmación con los cambios realizados actualmente o un nuevo mensaje de confirmación y solo debe realizarse en las confirmaciones que aún no se han enviado a un repositorio remoto.

git add . git commit --amend -m "Update roles for netlify-cms git gateway" 

¿Por qué debería escribir buenos mensajes de confirmación?

Podría decir: "Es solo un proyecto personal". Sí, ahora trabaja solo, pero ¿qué sucede cuando trabaja con un equipo o contribuye al código abierto?

Un mensaje de confirmación de Git bien elaborado es la mejor manera de comunicar el contexto sobre un cambio a otros desarrolladores que trabajan en ese proyecto y, de hecho, a su yo futuro.

¿Alguna vez ha intentado ejecutar git loguno de sus proyectos antiguos para ver los mensajes de confirmación "extraños" que ha utilizado desde su inicio? Puede ser difícil entender por qué hizo algunos cambios en el pasado, y deseará leer este artículo antes :).

Los mensajes de compromiso pueden comunicar adecuadamente por qué se realizó un cambio y comprender que hace que el desarrollo y la colaboración sean más eficientes.

Cómo escribir mensajes de confirmación con Git

Antes, solo usaba git commit -m "Fix X to allow Y to use Z"en mis proyectos personales con solo un tema y sin descripción adicional. Esto es ideal para arreglos pequeños y claros como git commit -m "Fix typo in README.md, pero en casos de cambios más extensos, necesitaría agregar algunos detalles adicionales.

Método editor

Ejecute git commitsin un mensaje u opción y abrirá su editor de texto predeterminado para escribir un mensaje de confirmación.

Para configurar su editor "predeterminado":

git config --global core.editor nano 

Esto configuraría Git para usar nano como su editor predeterminado. Reemplace "nano" por "emacs", "vim" o lo que prefiera.

En el editor abierto, la primera línea es el asunto (descripción corta), deje una línea en blanco después y todo lo demás es la descripción extendida (cuerpo).

Método de línea de comandos

git commit -m "Subject" -m "Description..." 

La primera -mopción es el tema (descripción breve) y la siguiente es la descripción extendida (cuerpo).

Cómo escribir buenos mensajes de confirmación

Hay varias convenciones utilizadas por diferentes equipos y desarrolladores para escribir buenos mensajes de confirmación. Solo esbozaré algunas reglas generales y consejos para escribir mensajes de confirmación; tienes que decidir qué convención quieres seguir. Y si trabajas para una empresa o contribuyes al código abierto, tienes que adaptarte a su convención :).

Para mantener la coherencia, puede utilizar una convención para el trabajo y otra para proyectos personales, ya que puede cambiar de trabajo en algún momento y la convención también puede cambiar.

Asegúrese de revisar este hilo para conocer algunas convenciones increíbles de mensajes de confirmación o agregue la suya para ayudar a alguien a tomar una decisión.

Aquí hay una gran plantilla de un buen mensaje de confirmación escrito originalmente por Tim pope

Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here - Use a hanging indent If you use an issue tracker, add a reference(s) to them at the bottom, like so: Resolves: #123 

Se ve genial, ¿verdad? Así es como puedes hacer que el tuyo también sea genial:

  1. Especifique el tipo de compromiso:
  • hazaña: la nueva función que está agregando a una aplicación en particular
  • fix: A bug fix
  • style: Feature and updates related to styling
  • refactor: Refactoring a specific section of the codebase
  • test: Everything related to testing
  • docs: Everything related to documentation
  • chore: Regular code maintenance.[ You can also use emojis to represent commit types]
  1. Separate the subject from the body with a blank line
  2. Your commit message should not contain any whitespace errors
  3. Remove unnecessary punctuation marks
  4. Do not end the subject line with a period
  5. Capitalize the subject line and each paragraph
  6. Use the imperative mood in the subject line
  7. Use the body to explain what changes you have made and why you made them.
  8. Do not assume the reviewer understands what the original problem was, ensure you add it.
  9. Do not think your code is self-explanatory
  10. Follow the commit convention defined by your team

Conclusion

The most important part of a commit message is that it should be clear and meaningful. In the long run, writing good commit messages shows how much of a collaborator you are. The benefits of writing good commit messages are not only limited to your team, but indeed expand to yourself and future contributors.

Want to learn more about Git and become a professional "version controller"? Check out these excellent resources:

  • //try.github.io/
  • //git-scm.com/book/en/v2
  • //www.git-tower.com/learn/
  • //learngitbranching.js.org/
  • //github.com/commitizen/cz-cli