¿Cada cuánto debería hacer un commit?
A menudo. Es mejor hacer commits pequeños, agrupando pequeñas mejoras o acciones, que un commit con todo lo que se quiere hacer.
Como decía Julio César:divide y vencerás. Divide la tarea en trozos pequeños. Cada trozo es un commit. Avanza en tu tarea y plasma esos cambios con frecuencia.
Esto, además de ayudarte con la productividad, también puede ser útil para tener siempre una copia de seguridad de tu trabajo o, también, para que cualquier otra persona pueda retomar tu trabajo desde el punto que lo dejaste.
La lista de commits cuenta la historia del proyecto. Leerlo debería ayudar a cualquier persona a entender la evolución del proyecto.
También es útil que sincronices regularmente la rama de trabajo con la rama en la que pretendes fusionar tus cambios mientras estás trabajando en ella. De esta forma evitarás conflictos en el futuro y si los hay serán lo suficientemente pequeños para que puedas lidiar con ellos.
Hacer commit a menudo no significa que debas hacer commits sin sentido. Graba tus progresos en iteraciones pequeñas pero que tengan un significado y que, si puede ser, no deje tu aplicación o proyecto sin funcionar.
¿Cómo puedo escribir un buen mensaje de commit?
Escribir buenos mensajes de commit es importante para que el histórico de tu proyecto sea legible, fácilmente escaneable y, obviamente, comprensible por cualquier persona que participe en el proyecto.
Por ello voy a darte6 reglas para escribir un buen mensaje de commit:
1. Usa el verbo imperativo (Add,Change,Fix,Remove)
Aunque el mensaje puede sonar un poco brusco, el verbo en forma imperativa es una buena manera de expresar la acción que se realiza en el commit. Por ejemplo,Add significa que se añade un nuevo archivo,Changesignifica que se modifica un archivo existente yFixsignifica que se arregla un bug.
Ejemplo de cómo los mensajes se van degenerando…
Sé que muchas veces estamos tentados a escribirlo en pasado“Added…“,“Fixed…” o“Removed…”pero cada commit hay que entenderlo como una instrucción para
cambiar el estado del proyecto. Dicho de otro modo, el verbo imperativo nos permite saber en qué estado queremos que el proyecto se encuentre en el momento de añadir el commit.
Sólo hay que ver también los mensajes de commit que el propio Git nos añade. Al hacer merge de una rama, por ejemplo, usaMerge branch.
Lo mejor es que el mensaje del commit complete esta frase:“Si aplico este commit, entonces este commit…”
- ...add a new search feature
- ...fix a problem with the topbar
- ...change the default system color
- ...remove a random notification
2. No uses punto final ni puntos suspensivos en tus mensajesUsar puntuación, más allá de las comas, es innecesario a la hora de crear un buen mensaje de commit. Cada carácter cuenta a la hora de describir un cambio, así que no lo desperdicies con puntos innecesarios.
git commit -m "Add new search feature." # Mal. Con punto final.
git commit -m "Fix a problem with the topbar..." # Mal. Puntos suspensi\
vos.
git commit -m "Change the default system color" # Bien.¿Por qué? El primer mensaje de commit es el título del commit. Y según las reglas de puntuación para títulos, tanto en castellano como en inglés, estos no llevan puntuación final. Sobre los puntos suspensivos… ¡Nuestros commits no deberían tener ningún suspense! Deben ser una instrucción clara y concisa.
Si te fijas, los commits que genera GitHub no tienen puntos suspensivos ni punto final en ningún caso.
Los mensajes que crea GitHub al fusionar una rama no usa puntuación al final. Para seguir esta regla, debemos tratar el primer mensaje del commit como el título o asunto.
3. Usa como máximo 50 caracteres para tu mensaje de commit
Sé corto y conciso. Si tienes mucho que explicar es probable que tu commit contenga demasiados cambios. ¿Puedes separarlo en diferentes commits? Pues entonces hazlo.
Haz que el mensaje sea claro, conciso y directo para que realmente refleje los cambios que contiene.
# MAL. Muy largo.
git commit -m "Add new search feature and change typography to improve performance"
# BIEN. Corto, comprensible.
git commit -m "Add new search feature"
# BIEN. Al grano pero con detalle.
git commit -m "Change typography to improve performance"
4. Añade todo el contexto que sea necesario en el cuerpo del
mensaje de commitA veces necesitas proveer demáscontextoatu commit. Para ello, en lugar de saturar el sumario del commit, añade información que sea necesaria en el cuerpo del mensaje.
Puedes lograrlo usando git commit -m “Add summary of commit” -m “This is a message to add more context.”pero en estos casos lo mejor es que uses directamente git commitde esta forma:
git commitEsto te permitirá añadir fácilmente un mensaje de commit con saltos de línea usando el editor.
Como hemos comentado antes, el primer mensaje de commit es el título del mismo. Pero el resto de mensajes pertenece al cuerpo y, por lo tanto, sí debes usar todas las reglas de puntuación que tendría un texto normal.
5. Usa un prefijo para tus commits para hacerlos más semánticos
Cuando un proyecto crece, es necesario que existan ciertas reglas para que el historial sea legible. Para ello, puedes añadir un prefijo para darle más significado a los commits que realizas. A esto se le llamacommitssemánticosy se haría de la siguiente manera:
tipo-de-commit(scope): descripcion>
Por ejemplo:
feat(search): add new search feature
^--^^------^ ^--------------------^
│ │ |
│ | └--> # Descripción del cambio
| |
| └──> # Contexto del cambio
|
└──------> # Tipo del cambioEn mono-repositorios multi-paquete, puedes añadir también la información del paquete que es afectado por el commit. Se le conoce comoscopey sería de la siguiente forma:
feat(backend): add filter for cars
fix(web): remove wrong colorSobre el tipo de cambio, lo mínimo es diferenciar entrefixyfeatpero existen diferentes convenciones. Una de ellas, bastante famosa, es laconvención que sigue el framework Angular²⁹.
Estos serían los prefijos:
- feat: para una nueva característica para el usuario. - fix: para un bug que afecta al usuario. - perf: para cambios que mejoran el rendimiento del sitio. - build: para cambios en el sistema de build, tareas de despliegue o instalación. - ci: para cambios en la integración continua. - docs: para cambios en la documentación. - refactor: para refactorización del código como cambios de nombre de variables o funciones. - style: para cambios de formato, tabulaciones, espacios o puntos y coma, etc; no afectan al usuario. - test: para tests o refactorización de uno ya existente.
Otra ventaja muy importante de utilizar commits semánticos es que podrás leer el historial para publicar nuevas versiones de un paquete, desplegar nuevas versiones de una aplicación o generar un CHANGELOG con todos los cambios.
6. Considera usar utilidades para hacer commit
Puedes usarhuskypara ejecutar scripts o comandos antes de realizar diferentes acciones sobre el repositorio, gracias a los hooks de git. Por ejemplo, puedes ejecutar los tests antes de subir los cambios al repositorio remoto.
# instalamos las dependencias
npm install husky --save-dev
npx husky install
# iniciamos husky en nuestro repositorio
npm set-script prepare "husky install"
npm run prepare
# creamos un hook para que pase los tests antes de hacer push
npx husky add .husky/pre-push "npm test"
git add .husky/pre-push
git commit -m "Keep calm and commit"
# los tests se ejecutarán antes de realizar el push
git push -u origin masterConcommitlintpuedes asegurarte de que los commits sean semánticos, legibles y sigan una convención que elijas.
Para instalarcommitlint:
# Install commitlint cli and conventional config
npm install --save-dev @commitlint/{config-conventional,cli}
# For Windows:
npm install --save-dev @commitlint/config-conventional @commitlint/cli
# Añadir hook para revisar el mensaje de commit
npx husky add .husky/commit-msg 'npx --no-install commitlint --edit "$1 "'Puedes usar sistemas comoconventional-changelogpara leer el CHANGELOG y generar nuevas versiones o publicar paquetes. También concommitizenpuedes usar una línea de comandos que te haga elegir el tipo de commit y así no tener que depender de realizar esto manualmente en el propio mensaje.
¿Cómo puedo escribir un buen nombre de rama?
Al crear una rama en Git existen multitud de posibles convenciones. Voy a darte algunos consejos que seguro te ayudarán a la hora de elegir un buen nombre para tu rama. Sin embargo, me gustaría que también tengas en cuenta quedependiendo de la metodología de trabajo de tu organización, empresa o equipo, estos consejos pueden ser más o menos válidos.
Estos consejos están basados en mi experiencia después de muchos años trabajando en diferentes empresas y equipos de desarrollo.
1. Sé consistente al nombrar tus ramas
Sea como sea que al final decidas crear los nombres de las ramas, deberías usar siempre el mismo patrón. Sé consistente y documenta si hace falta las decisiones tomadas, de forma que todo el equipo de trabajo pueda entender las reglas que hay que seguir.
Por ejemplo, la primera decisión sería hacer que los nombres de las ramas sean todo en minúscula y que las palabras sean separadas por un guión-. Sea esto así o de otra forma si prefieres, lo importante es que todas las ramas sigan el patrón decidido.
2. Usa el nombre de la acción que se realiza en la rama
De la misma forma que en los commits semánticos indicábamos qué tipo de acción realiza el commit, también en las ramas se puede hacer algo similar. No hace falta ser tan específico como el commit pero sí puede ayudarte a saber de qué trata la rama rápidamente.
- bug: Cambios de código para arreglar un bug conocido.
- feature: Desarrollo de una nueva característica.
- experiment: Experimentos que nunca serán fusionados.
- hotfix: Cambio rápido de un error crítico.
Con esto en mente, algunos ejemplos de nombre de ramas serían:
bug/avoid-creating-lead-twice
feature/add-new-user-form
experiment/try-new-ui-design
hotfix/fix-typo-in-name3. Usa los IDs de JIRA o el sistema de tickets que uses
Aunque la convención anterior es una buena forma de identificar de qué tipo de rama se trata, es muy importante que el nombre de la rama sea único. Y lo cierto es que usando palabras no es difícil encontrarte dos veces la ramahotfix/fix-typo..
Además, parece que el nombre de la rama a veces no da el suficiente contexto para saber realmente en qué trabaja o qué soluciona. Para ello, una buena idea es adjuntar al principio del nombre de la rama la ID del ticket o de la issue que esté asociada. Eso, obviamente, si estás usando algún sistema para gestionar tu proyecto (que seguramente debería ser así, por rudimentario que sea el sistema).
De esta forma, tus ramas podrían ser así:
989-hotfix/fix-typo-in-name
1110-feature/add-new-user-form
1240-experiment/try-new-ui-design
1255-hotfix/fix-typo-in-nameAhora es mucho más fácil buscar más contexto sobre estas ramas, pese a que no quede claro con su propio nombre. Además, esto hace que buscar ramas sobre soluciones anteriores sea mucho más sencillo. De esta forma puedes ejecutar git checkouto git switchseguido del inicio del número de ticket o issue para ver si ya existe una rama creada y, si lo está, ver qué cambios se han hecho en ella.
$ git switch 12[pulsa-tab]
1240-experiment/try-new-ui-design
1255-hotfix/fix-typo-in-name¿Debería alterar el historial de mi proyecto?
No. Excepto si tienes muy buenas razones. Y tienen que ser muy buenas.
La única buena razón para hacer esto es que has publicado una contraseña, una llave de una API o información sensible que no debería estar en el historia. Incluso en ese caso, si es posible, esmejorideareiniciarlacontraseñaolallave.¿Por qué? Porque esa información ya es vulnerable al haber sido expuesta y borrarla del historial no garantiza nada.
Si eso no fuese posible, entonces sí puedes hacer un git rebasepara cambiar el historial de tu repositorio. Pero ten en cuenta que esto no es normalmente una buena idea y es mejor evitarlo. Piensa que al cambiar el histórico, todos las personas con acceso al repositorio remoto deberán sincronizar de nuevo correctamente sus repositorios locales.
Si, por ejemplo, hay un error en el código o has subido un commit que está mal, entonces siempre es mejor, si es posible, revertir el commit con git reverty dejar reflejado en el historial que se hizo ese cambio.
De hecho, dejar en el historial este tipo de errores es una buena idea. Los errores y fallos son una parte importante de la evolución de un proyecto y es importante que sean reflejados en el historial. Para no repetirlos en el futuro lo mejor no es ocultarlos, es más bien todo lo contrario.
Un sitio donde puede tener sentido hacer rebase es en las ramas. Cuando estás desarrollando en una rama, puedes hacerrebasecon la rama principal. De esta forma reescribes el historial de la rama de desarrollo y puedes evitar los commits deMergeque pueden añadir ruido al historial.
No hagas commit de código generado ni configuración particular
Un error muy común que se puede ver en repositorios es el de guardar archivos que han sido generados automáticamente por algún proceso o el de guardar configuración de un usuario o editor en concreto. Por ejemplo, imagina que tienes una web y que antes de desplegarla tienes que generar una carpetabuildcon los archivos estáticos minificados y listos para subir. Pues bien, la carpetabuilddebería ser ignorada por Git.
Esto se hace por diversos motivos:
- Añaden ruido innecesario al historial de cambios y se puede hacer molesto a la hora de revisar código. - A la larga hará que nuestro repositorio se vuelva más pesado por culpa de estos ficheros que cambian constantemente y pueden ser bastante complejos.
Así queno lo hagas. Usa correctamente tu archivo.gitignorepara evitar controlar estos ficheros en tu repositorio.
Respecto a configuraciones particulares, como la configuración del editor, existen normalmente mejores soluciones a Git. Ten en cuenta que esta configuración puede entrar en conflicto con la configuración de otra persona que también esté trabajando en ese mismo proyecto.
¿Qué debo tener en cuenta para hacer una buena Pull Request?
Crear una buena Pull Request es muy importante para conseguir que tus contribuciones lleguen a ser fusionadas en la rama principal del proyecto. Y no hay nada más frustrante que crear código para que luego no se haga nada con él… ¡Así que revisa estas reglas para que tus PRs lleguen a buen puerto!
1. Léete el archivo CONTRIBUTING.md o sigue el estilo del
repositorioAntes de querer contribuir a un proyecto, busca el archivo CONTRIBUTING.md que se suele encontrar en la raíz del repositorio. No todos los proyectos cuentan con uno pero, si lo tiene, es vital que lo leas, ya que normalmente explica todo lo que debes tener en cuenta antes de abrir unaPull Request.
Si no lo encuentras, no te preocupes. Estudia el repositorio. ¿Qué estilo de commits utilizan? ¿Qué nombre de ramas? ¿Usan un estilo en concreto a la hora de escribir el código? Sigue al máximo la forma de trabajar de los demás.
LapropiaGitHubtienemuchosrepositoriospúblicosconunficheroContributing. Revísalosporque a veces no aceptan ciertos tipos de contribuciones.
2. Respeta el estilo del repositorio
A veces un repositorio de código sigue un estilo particular. Por ejemplo, algunos de los repositorios de JavaScript pueden no usar puntos y coma. Otros sí. Y, en ocasiones, tienen un linter configurado para revisar que el código siga ese estilo.
Independientemente de que tenga linter configurado o no, es importante que el código que subes siga el estilo del repositorio. Por ejemplo, no te dediques a cambiar en tu código las comillas simples por las dobles, sólo por el simple hecho que te gustan más.
Si lo haces, vasadistraeralaspersonasquerevisantucódigoy pueden no aceptar tus cambios por traer cambios que no vienen a cuento. Así que evítalo a toda costa.
Si todavía crees que es imperativo el cambio de estilo… lo mejor es que primero abras unaissueen el repositorio y expongas las razones por las que crees que es necesario.
3. Enfoca tu código en una sola cosa
¿Quieres arreglar unbugde una aplicación? ¿Quieres añadir una nueva funcionalidad? ¿Quieres añadir un nuevo test? ¿Hay que mover un directorio? Pues separa
cada una en una Pull Request diferente.
Es mucho más fácil revisar y aceptar una Pull Request que hace una solacosa a revisar una Pull Request que aprovecha a hacer muchas cosas.
Por ejemplo: Imagina que quieres arreglar un bug y que, hacerlo, es una sola línea de código. Pero te das cuenta que no te gusta la localización del fichero y, además de arreglar el problema, decides mover el fichero a otro lugar.
Esto hará que en la Pull Request tu cambio, que parecía sencillo, se convierta en una gran tarea y que la diferencia de código entre la versión actual y la que tu quieres fusionar ahora sean todas las líneas del fichero.
Es mejor, en ese caso, que hagas dos Pull Requests. Una para arreglar el bug y otra para mover el fichero.
Es evidente que cuantas más líneas de código tenga que revisar una persona… más nerviosa se va a poner. Menos es más.
Lo mejor que puedes hacer al crear una Pull Request es empatizar con las personas que van a revisarla.¿Cómo te sentirías tú ante una PR de mil líneas de código? ¿Cómo te sentirías tú ante una PR de una línea de código?
Esto no quiere decir que hagas una Pull Request para cada commit. Una Pull Request puede, y seguramente debe, tener más de un commit que explique cada pequeño cambio que se ha realizado para lograr la finalidad de la Pull Request.
4. Explica tu Pull Request
Mucha gente dice que el código habla por si solo y, aunque es genial que tu código sea lo suficientemente explicativo para que la gente sepa lo que hace de un vistazo, es muy buena idea que tu Pull Request sea acompañada de una buena explicación de qué has hecho y qué quieres conseguir, además de cualquier otra información que pueda ayudar a la gente a tomar una decisión con tu código.
Añadir una descripción a tu Pull Request descriptiva e incluso actualizarlo si es necesario, puede ayudar a ser mejor evaluada
Y si una imagen vale más que mil palabras. ¿Qué puede valer un GIF o un vídeo mostrando la funcionalidad? Existen muchas aplicaciones y herramientas que nos permiten grabar la pantalla. Yo en mi caso uso en macOS la aplicaciónCleanShot³⁰.
³⁰https://cleanshot.com/Cambia tu rama master a main o similares
Desde el 1 de octubre de 2020,GitHub cambió el nombre de la rama principal³¹por defecto de los repositorios. Su nombre pasó de sermastera main. Más tarde, el 10 de marzo de 2021,GitLab anunció lo mismo.³²
Este cambio viene por lasconnotaciones racistasque tienen los términos master yslave. En el año 2020 surgieron muchas protestas por el uso de terminología anticuada o con percepción discriminatoria en muchos proyectos tecnológicos (otro ejemplo es el uso deblacklistpara algo negativo ywhitelistpara algo positivo).
En junio de 2020 laSoftware Freedom Conservancypublicó unadeclaración donde resumía las razones por las que el términomasterera ofensivo³³.
El nombre de master como rama principal va a quedar completamente obsoleto y, poco a poco, veremos menos repositorios usándolo
Pese a que tú, personalmente, no te sientas ofendido por este término lo cierto es quealgunas personas sí sienten como un agravio este uso y, simplemente, por empatía se puede entender que es una buena ideacambiar la rama principal por defecto.
Si en realidad no estás de acuerdo con este cambio y las razones que hay detrás… igualmente te recomiendo adoptar el cambio. Al final hay que entender que es el nuevo nombre de rama principal que se va a usar en todos los proyectos y servicios, por lo quecuanto antes lo asimiles, mejor.
- ³¹ https://github.blog/changelog/2020-10-01-the-default-branch-for-newly-created-repositories-is-now-main/
- ³² https://sfconservancy.org/news/2020/jun/23/gitbranchname/
- ³³ https://sfconservancy.org/news/2020/jun/23/gitbranchname/
De hecho, ten en cuenta que desde la versión 2.28.0 de git , después de iniciar un repositorio local, ya te advierte que usar master como rama principal va a cambiar en próximas versiones.
hint: Using’master’as the name for the initial branch. hint: This default branch name is subject to change. hint: To configure the initial branch name to use hint: in all of your new repositories, which will suppress hint: this warning, call: hint: hint: git config —global init.defaultBranch
Mi recomendación es que ejecutes git config —global init.defaultBranch main en tu terminal, de forma que por defecto use la ramamainen todos tus nuevos repositorios nuevos. Así encajará con GitHub, que es uno de los servicios más usados para hospedar repositorios, y otros servicios que, seguro, también van a adoptar este cambio por convergencia.
Ten en cuenta quela rama principal, como hemos explicado, se puede llamar con el nombre que prefieras. Si ha sidomasterha sido, realmente, porque históricamente ha sido así pero nada impide que ya existiesen repos con nombres para su rama principal comodevelopo trunk. Al final parece que la preferida va a sermainpero puedes usar tu creatividad si lo prefieres.
Ahora… ¿Deberías cambiar tus ramasmastera main? Si estás creando un repositorio nuevo es obvio que es buena idea crearla ya conmaincomo rama principal. Pero… ¿qué pasa con los repositorios que ya tenemos?
Cómo migrar la rama principal demastera main
Primero, tenemos que mover la ramamastera main. Para ello usamos el comando git branch. El parámetro—movees el que indica que es un movimiento de rama o renombre. De esta forma todo el historial de commits demasterestará disponible también en la nueva rama.
$ git branch --move master mainAhora, tenemos que actualizar el repositorio remoto (si es que lo tenemos). Recuerda que, si no, el cambio se quedaría sólo en tu máquina. También debemos usar el parámetro—set-upstreampara indicar que también será la rama remota por defecto. De esta forma, cualquier git pullque hagamos más tarde, se hará sobre la ramamainremota.
# actualizamos el repositorio remoto origin
$ git push --set-upstream origin mainTotal 0 (delta 0 ), reused 0 (delta 0 ), pack-reused 0 remote: remote: Create a pull request for ‘main’on GitHub by visiting: remote: https://github.com/tu-usuario/react-slidy/pull/new/main remote: To github.com:tu-usuario/react-slidy.git * [new branch] main -> main Branch’main’set up to track remote branch’main’from ‘origin’.
Ahora tenemos que asegurarnos que nuestro punteroHEADapunta también a esta
nueva rama remotamain.
# movemos el puntero HEAD a la rama main remota de origin
$ git remote set-head origin main
# para asegurarnos que funciona podemos ejecutar
$ git branch -r
origin/HEAD -> origin/main # esto es lo que queremosAhora tenemos que cambiar la rama por defecto en el servicio de hospedaje de repositorios que usemos. Vamos a ver cómo hacerlo en GitHub pero en otros productos sería muy similar.
En el caso de GitHub, tenemos que ir a nuestro repositorio en GitHub y Settings -> Branches.
Cambia la rama por defecto de master a mainDebajo del títuloDefault Branch, encontrarás la rama principal (que debería ser mastero la que sea que estuvieses usando hasta ahora). Encontrarás dos iconos a su derecha. Un lápiz y dos flechas. Pulsa las dos flechas, haz clic en el desplegable y selecciona la nueva rama main. Finalmente, pulsaUpdate.
Pulsa las dos flechas para que se abra una ventana flotante donde seguiremos con el cambio de rama por defecto
Renombrando la rama de master a mainTe aparecerá un avisoindicando que cambiar tu rama por defecto puede tener consecuencias no esperadas que pueden afectar a nuevas PRs y clonaciones. Pulsamos el botón que dice que lo entendemos y que queremos actualizar la rama igualmente… ¡y ya lo habremos conseguido!
¿Qué consecuencias inesperadas tiene esto? Pues bastantes. Para empezar si usas Travis,CircleCIo GitHub Actions, deberás asegurarte que ahora escuchan cada push a la nueva ramamainen lugar de la que tenía antes. Otro ejemplo puede ser los servicios deVerceloNetlifyque, normalmente, hacen despliegues automáticos dependiendo de la rama. Revisa sus configuraciones para asegurarte que usan la rama correcta para los despliegues a producción. También, como veremos más adelante, otras personas tendrán que hacer cambios a su entorno local.
Sin embargo, todavía nos queda una cosa importante. Eliminarnuestrarama master. De lo contrario, todavía estará por ahí y las personas que trabajan en este repositorio podrían confundirse, intentar usarla y actualizarla.
Para ello vamos a actualizar el repositorio remotooriginy eliminar la rama master de ahí.
$ git push origin --delete master
To github.com:tu-usuario/react-slidy.git- [deleted] master
Ahora mismo tú lo tienes todo solucionado. ¡Felicidades! Pero…¿Qué pasa con las personas que colaboran contigo? Tienen dos opciones: eliminar su repositorio local y volver a clonarlo (la solución que siempre funciona) o podemos ejecutar una serie de comandos para asegurarnos que usamos la rama correcta.
# vamos a la rama master
$ git checkout master
# recuperamos todas las ramas disponibles del repo remoto
$ git fetch --all
Fetching origin
# actualizamos el puntero HEAD
$ git remote set-head origin --auto
origin/HEADset to main
# cambiamos nuestra rama local
$ git branch --set-upstream-to origin/main
Branch 'main 'set up to track remote branch 'main 'from 'origin '.
# (opcional) renombramos nuestra rama local master
$ git branch -m master mainFirma correctamente tus commit con GPG
Al inicio del curso, en la sección deInstalando y Configurando Git, hemos visto cómo podíamos configurar Git para quefirmelos commits con nuestra autoría. Para ello, tenemos que configurar el nombre y correo electrónico.
Esto es importante ya que va aayudar al equipo a saber quién realizó ciertos cambiosy pedirle apoyo en el caso que algo no quede claro. Hay que verlo como una forma de poder conseguir más contexto yno de control de quién ha cometido un fallo.
Lo haríamos con dos comandos:
$ git config --global user.name "<tu nombre>"
$ git config --global user.email "<tu email>"
Por ejemplo:
$ git config --global user.name "Miguel Ángel Durán"
$ git config --global user.email "miduga@gmail.com"Sin embargo debes saber algo. Este tipo defirmano es segura. Como te habrás dado cuenta, cualquier persona podría usar los datos de otra persona y hacerse pasar por ella…
Para mejorar la seguridad de tus commits, y que no quede duda de la autoría de ellos, puedes firmarlos con una llave GPG y, de esta forma, mostrar que ha sido verificado.
Generando llaves GPG
GPG es un software de cifrado híbrido que combina criptografía convencional de claves simétricas para la rapidez con criptografía de claves públicas para el fácil compartimiento de claves seguras.
Primero, vamos a ver si tenemos instalada la implementación de GPG en nuestro sistema. Normalmente se usaGnuPGpor lo que podemos ver si lo tenemos instalado ejecutando el siguiente comando en la terminal.
$ gpg --version
gpg (GnuPG) 2 .3.3
libgcrypt 1 .9.4
Copyright(C) 2021 Free Software Foundation, Inc.
License GNU GPL-3.0-or-later <https://gnu.org/licenses/gpl.html>
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
Home: /Users/tu-usuario/.gnupg
Algoritmos disponibles:
Clave pública: RSA, ELG, DSA, ECDH, ECDSA, EDDSA
Cifrado: IDEA, 3DES, CAST5, BLOWFISH, AES, AES192, AES256, TWOFISH,
CAMELLIA128, CAMELLIA192, CAMELLIA256
AEAD: EAX, OCB
Resumen: SHA1, RIPEMD160, SHA256, SHA384, SHA512, SHA224
Compresión: Sin comprimir, ZIP, ZLIB, BZIP2Si te aparece que no encuentra el comando, deberás instalarlo.
Si estás en Windows, te recomiendo que uses la máquina virtual de Ubuntu para conseguirlo y sigas los pasos para Debian, que sería ejecutar el comandosudo apt-get install gnupg.
En Linux, simplemente, usa el gestor de paquetes adecuado a tu sistema.
Si estás en macOSlo mejor es usar Homebrew, como hemos hecho anteriormente con otros paquetes, y ejecutar el comandobrew install gnupg.
GnuPG permite cifrar y firmar tus datos y comunicaciones, incluye un sistema versátil de gestión de claves, así como módulos de acceso para toda clase de directorios de claves públicas.
Ahora ya podemos generar la llave GPG. Para ello, vamos a ejecutar el comandogpg —full-generate-key
Los pasos que debemos seguir serán:
- ElegirRSA (sign only)como el tipo de clave. 2. Elegir 4096 como el tamaño de la clave. 3. Sin expiración (o puedes elegir la fecha que prefieras, pero tendrás que renovarla). 4. Tu nombre real o nombre de usuario de GitHub. 5. El correo electrónico que usas actualmente para firmar el commit. (puedes ejecutar git config —global user.emailpara encontrarlo) 6. Añade un comentario como Git Sign Commitspara saber de qué va la llave.
Si quieres, puedesañadirunacontraseñaparatullave. Puede ser útil por si alguien obtiene acceso a tu ordenador y no le sirva simplemente copiándola. Aunque si alguien tiene acceso a tu ordenador, seguramente este sea el menor de tus problemas. Una vez generada, podemos recuperar la información de la llave ejecutando:
gpg --list-secret-keys --keyid-format SHORT
/Users/tu-usuario/.gnupg/pubring.kbx
---------------------------------
sec rsa4096/A2XXXXXXX 2022 -01-02[SC] [caduca: 2024 -01-02]
7F1B507XXXXXXXXXXXXXXXXXXXXXXXX
uid [ absoluta] Miguel Ángel Durán <miduga@gmail.com>Después delrsa4096, tenemosA2XXXXXXXque sería la ID de nuestra llave y, en este caso, es lo que nos interesa. En este caso, ten en cuenta, que tu ID será diferente y, por lo tanto, debes seguir los pasos usando tu llave y no la mía.
Ahora podemos indicarle a Git que queremos usar esa llave para firmar nuestros commits. Para ello, ejecutamos el comando git config —global user.signingkey A2XXXXXXX.
También necesitamos asegurarnos que elgpg-agentestá ejecutándose en nuestro sistema y además tenemos que informarle del shell actual que estamos usando para ello ejecutamos estos dos comandos:
# Reiniciamos el agente de gpg
gpgconf --kill gpg-agent
gpgconf --launch gpg-agent
# variable de entorno que le informa del shell actual
exportGPG_TTY= $( tty )El segundo comando, la idea, es lo que lo añadas en tu fichero/.zshrco/.bashrc para que se inicie siempre que levantes una nueva sesión de tu línea de comandos.
Firmando commits con llave GPG
Ahoraya podemos firmar nuestros commits. Para ello, cuando hagamos un commit, debemos añadir el parámetro-Sy utilizará la llave que hemos configurado previamente.
$ git commit -m "Add signed commit" -S
[main aafac37] Add signed commit
1 file changed, 127 insertions(+)Si añadiste una contraseña a tu llave GPG, es normal que te pida una contraseña en este punto. De esta forma se asegurará que eres tú quien firma el commit…
Obviamente no vas a querer añadir en cadacommitel parámetro-S. Si quieres firmar todos tus commits a partir de ahora, lo mejor es que lo indiques en la configuración de Git.
# firma automáticamente todos los commits
$ git config --global commit.gpgsigntrueEs posible que en cada commit te pida la contraseña. En algunos sistemas puede guardarse en el llavero del sistema pero… si no lo hace, puede ser un poco molesto. Según el sistema hay, igualmente, formas de saltarse pero escapa de lo que se pretende cubrir aquí.
Configurando GitHub
Ahora ya sólo nos queda enlazar nuestra llave local con los repositorios remotos. Vamos a ver cómo hacerlo en GitHub, que es el proveedor más usado, pero los pasos deben ser muy similares con otros como BitBucket o GitLab.
Primero, tenemos que recuperar el valor de la llave GPG que hemos configurado previamente.
# Recuperamos la llave GPG para usarla en GitHub
$ gpg --armor --export A2XXXXX
-----BEGIN PGP PUBLIC KEY BLOCK-----
mQINBGHRoEYBEACYl6xEQ02EJwH1yODpEaxLeLR8EdMgY8RAbriNLROkQbqnkhEH
...
DtcqaBqqquiolNPUb9ZlkubLb89Q84=
=I123T+
-----END PGP PUBLIC KEY BLOCK-----
# O mejor...
$ gpg --armor --export A2XXXXX | pbcopyAhora dirígete a https://github.com/settings/gpg/new y pega en la caja de texto la llave GPG que acabas de copiar. Después, haz click en el botónAdd GPG key.
Y, con esto, ya podrías empujar tus commits a GitHub y ver en el repositorio que el historial de commits muestra aquellos que han sido firmados con llave GPG con una nueva etiqueta llamadaVerified.
En GitHub nos mostrará información sobre si un commit ha sido firmado o no con llaves GPG y, de esta forma, asegurarnos que la autoría es real y no simulada
¿Cómo debería revisar una Pull Request?
Cuando recibimos una nueva Pull Request, debemos revisarla y aceptarla, rechazarla o… ignorarla. Bueno, esto último no lo hagas. De hecho ese es el primer consejo.
Voy a compartirte una serie de consejos y buenas prácticas a seguir a la hora de revisar una petición de cambios en un repositorio (Pull Request). Estos consejos pueden servirte tanto para trabajar en una empresa como en un proyecto de código abierto.
Valora el tiempo de la persona y empatiza
Alguien ha dedicado tiempo de su vida en crear una petición de código en tu proyecto o en el proyecto de la empresa. ¿No te gusta la Pull Request? ¿No estás de acuerdo? ¿No la piensas aceptar? No pasa nada, ya veremos cómo podemos lidiar con ello. Pero aún asídebemos valorar el tiempo que ha dedicado, seguramente, con su mejor intención.
La empatía es, seguramente, una de las mayores virtudescon las que se puede contar en el mundo de la programación. Ponernos en el lugar de la persona y de cómo nos gustaría a nosotros que nos tratasen.
Intenta dedicarle tiempo de calidad a la revisión de la petición de cambios. Considera que, pese a no estar al 100% de acuerdo con los cambios, igual puedes fusionarla si satisface casi todas las condiciones y el resto podrías adaptarlas tú mismo más tarde.
Recuerda que el código no es de piedra, por lo que siempre puedes hacer cambios y mejoras sobre cualquier PR que recibas.
Proporciona siempre feedback positivo
Cuando reaccionamos a una Pull Request hay que tener en cuenta que hay una persona detrás. Está bien que expresemos nuestras opiniones y que pidamos cambios, perodebemos saber hacerlo para que la persona pueda recibir el mensaje y, además, mejorar con ello.
Si cuando damos feedback, este feedback no ayuda a la otra persona a mejorar el código o su nivel, entonces no es feedback, es otra cosa. Y esas otras cosas pueden disparar las emociones de las personas de forma innecesaria.
Compara las dos siguiente formas de dar el mismofeedback:
Esto está mal. ¡Usa el spread operator en lugar de poner tanto código!
¡Muchas gracias por colaborar en el proyecto! Esto soluciona al problema. ¡Es genial! Te sugiero que uses el spread operator en la línea 14. Creo que esto te ahorrará tres líneas y, además, hará que el código sea más legible. ¿Qué te parece?
Como puedes verambos mensajes valoran lo mismo pero lo hacen de formas muy distintas(y seguramente con resultados muy diferentes).
En el segundo mensaje sólo estamos valorando cosas positivas mientras le damos un feedback constructivo y, además, le decimos por qué se lo damos.
Recibir feedback es un regalo. También debemos saber recibir comentarios para mejorar como profesionales. Al final, debemos entender que si una persona nos pide cambios también lo hace con la mejor intención.
Concreción y claridad
Cuando comentamos una Pull Request debemos aportar claridad, brevedad y concreción. Dicho de otra forma, evitamos las generalidades y vamos al grano. De esta forma evitamos los malos entendidos, reducimos el alcance de la discusión y nos aseguramos de que la persona pueda entender nuestra opinión.
Compara las dos siguiente formas de dar el mismofeedback:
No me gustan los nombres de las variables. ¿Las puedes cambiar?
Creo que podríamos mejorar algunos nombres de variables. Por ejemplo, en lugar de la variable sent podríamos llamarle isSent para que quede claro que es un tipo de dato lógico. Lo mismo para called. Podríamos usar hasCalled. ¿Cómo lo ves?
También puedes utilizar las sugerencias de código, de forma que propongas una solución directa a la petición que tienes. De esta forma ofrecemos una solución alternativa a lo que ha hecho y no le bloqueamos mientras espera a hacer sus cambios para tener de nuevo nuestra opinión. Reducimos elfeedback loop.
En GitHub puedes proporcionar sugerencias de código en tu comentario. La persona que haya creado la PR podrá aceptar los cambios sugeridos directamente.
Entiende el contexto
No es lo mismo revisar una PR que contiene una nueva característica que puede romper la compatibilidad de una API a una petición de cambios que, pese a no tener un código perfecto, está arreglando un bug que bloquea producción o a cientos de usuarios.
Entiende que el contexto es importante a la hora de valorar estas peticiones. Es posible que a veces tengamos que poner paños calientes o parches a nuestro código y que, pese a no ser el más bonito, sí que cumpla su cometido.
Por ejemplo, si ves que hay algo que no te convence en el código, puedes añadir un comentario en la línea de código que ves mejora pero dejarlo para más adelante. Compara estas dos formas de dar feedback:
Buffffff, este cambio es inmantenible.
Entiendo que este cambio es importante para desbloquear los pases a producción. Fusionemos la rama y después trabajamos juntos para mejorar la solución, de forma que sea más mantenible. ¿Qué te parece?
El código está en constante evolución y mejora. Hay que tirar de pragmatismo en ocasiones.
Añade un archivo de CONTRIBUTING.md
Crea un archivoCONTRIBUTING.mden la raíz de tu repositorio para que puedas documentar los pasos que una persona debe realizar para poder aportar cambios a tu proyecto.
También puedes explicar el proceso de revisión de lasPull Requests, un código de conducta, los estándares de código y cualquier otra cosa que pueda ayudar a la gente a entender cómo contribuir al proyecto.