Pull Requests Joan Puigcerver Ibáñez j.puigcerveribanez@edu.gva.es Llicència: CC BY-NC-SA 4.0 (Reconeixement - NoComercial - CompartirIgual) 🅭 Pull Requests Una Sol·licitud de Incorporació o Pull Request (PR) és una sol·licitud per a incorporar canvis a una branca d'un repositori. Les PR poden ser utilitzats per a: Incorporar canvis d'una branca a una altra branca dins del mateix repositori. Incorporar canvis d'una bifurcació o fork al repositori principal. La utilització de les PR aporta molts avantatges, com ara: Revisió de canvis: Permet revisar els canvis realitzats abans de la seua integració al projecte. Debat de canvis: Facilita el debat i la revisió conjunta dels canvis amb altres desenvolupadors o col·laboradors. Automatització de tasques: Ofereix la possibilitat d'executar tasques automàtiques abans de la incorporació dels canvis, com ara la realització de proves o la comprovació de la qualitat del codi. Estratègia de ramificació: Permet incorporar els canvis de manera ordenada i controlada. Aquesta funcionalitat és essencial per a la col·laboració en projectes, especialment els de codi obert, on els mantenidors poden revisar els canvis proposats per la comunitat. Exemple de Pull Request a Material for MkDocs En el repositori Material for MkDocs existeixen múltiples PR on s'han realitzat canvis per a millorar el tema o actualitzar la documentació. Figura 1. Exemple de Pull Request en el repositori Material for MkDocs Creació d'una Pull Request Per crear una PR, cal accedir al teu fork o branca i fer clic al botó Pull Request. En el procés de creació d'una PR s'han de seleccionar els repositori i les branques associades a la PR: Base repository: Repositori on s'incorporaran els canvis. Base: Branca de destí on s'incorporaran els canvis. Head repository: Repositori on es troba la branca amb els canvis. Compare: Branca amb els canvis que es volen incorporar. A més, es pot afegir informació addicional com: Títol: Breu descripció dels canvis realitzats. Descripció: Informació addicional sobre els canvis realitzats. Creació d'una Pull Request En aquest exemple s'ha creat una PR per incorporar nous canvis a la documentació de Material for MkDocs. Base repository: squidfunk/mkdocs-material Base: Branca master Head repository: El fork joapuiib/mkdocs-material Compare: Branca feature/caption-docs Figura 2. Comparació de canvis en una Pull Request Una vegada creat la PR, es pot sol·licitar la revisió dels canvis a altres usuaris i realitzar els canvis necessaris fins a la seua acceptació. Les PR poden estar en quatre estats diferents: Esborrany (Draft): Creada, però no s'ha finalitzada. Oberta (Open): En procés de revisió i a punt per a ser fusionat. Fusionada (Merged): Acceptada i incorporada al repositori. Tancada (Closed): Rebutjada o tancada sense incorporar. Enllaçar incidències a una Pull Request Quan es treballa en un projecte, sovint les Pull Request estan relacionades amb incidències específiques. GitHub permet enllaçar-les de tal manera que, quan la PR és acceptada, les incidències es tancaran automàticament. A més, millora la traçabilitat del desenvolupament i facilita el seguiment dels canvis realitzats per a la resolució de les incidències. Documentació Linking a pull request to an issue – GitHub Docs Les incidències poden ser enllaçades a una PR de dues maneres: Mitjançant l'apartat Development en la barra lateral en la pàgina. Utilitzant paraules clau amb el número incidència en la descripció. close closes closed fix fixes fixed resolve resolves resolved Un exemple de sintaxi és: Closes #10 On #10 és el número d'incidència que es desitja enllaçar. Exemple d'incidències enllaçades a una PR La següent imatge mostra una PR sobre el repositori Material for MkDocs s'ha referenciat una incidència per resoldre la barra lateral en el navegador Firefox. Figura 3. Incidència enllaçada a una Pull Request Incorporació d'una Pull Request Quan una PR és acceptada, els canvis s'incorporen a la branca de destí i la PR és marcada com a fusionada. La incorporació del PR es pot realitzar de tres maneres diferents: Crear un commit de fusió: es crea un nou commit que incorpora els canvis de la PR, com en una Fusió de branques divergents. Fusió en un sol commit (squash): es fusionen tots els canvis de la PR en un sol commit mitjançant Merge squash. Canvi de base (rebase): es realitza un Canvi de base (rebase) de la branca de la PR respecte a la branca de destí i es fusiona mitjançant una Fusió directa. Recomanació La fusió en un sol commit (squash) és útil per a mantindre una història de commits més clara, ordenada i concisa. Si es desitja consultar el procés de revisió de la branca, sempre es pot accedir a la PR on es troben tots els canvis realitzats. Figura 4. Tipus de fusió d'una Pull Request Configuració de les Pull Requests El repositori pot ser configurat per habilitar les diferents tècniques de incorporació, entre altres configuracions a l'apartat Pull Requests de la configuració del repositori ( Settings). Figura 5. Configuració de les opcions de les Pull Requests Flux de treball El flux de treball amb les PR no és diferent a les a Estratègies de ramificació, sinó que ens proporciona un mecanisme addicional per a la revisió i incorporació de canvis. Aquest flux de treball pot ser el següent: En el mateix repositoriEn un fork ( Codi obert) Crear una nova branca per a realitzar els canvis. Realitzar els canvis en la branca. Crear una PR per a incorporar els canvis a la branca principal o de desenvolupament. Revisar i debatre els canvis amb els revisors. Actualitzar la PR amb els canvis necessaris o amb l'estat més recent de la branca de destí. Incorporar els canvis al repositori original. Crear un fork del repositori principal. Clonar el fork en el teu entorn de desenvolupament. Crear una branca per a realitzar els canvis. Realitzar els canvis en la branca. Publicar la branca en el fork. Crear una PR per a incorporar els canvis del fork al repositori principal. Revisar i debatre els canvis amb els revisors. Actualitzar la PR amb els canvis necessaris o amb l'estat més recent de la branca de destí. Incorporar els canvis al repositori original. Sincronitzar ( Sync) el fork amb els nous canvis del repositori original. Protecció de branques Per a evitar canvis no desitjats en les branques principals i evitar problemes deguts a una mala aplicació de les Estratègies de ramificació, les branques importants (com main o develop) poden ser protegides mitjançant conjunts de regles (Rulesets). Per configurar les regles de protecció de branques, cal accedir a la configuració del repositori Settings i buscar l'apartat Rules. Aquestes regles permeten definir les condicions per modificar la branca especificada, com ara: Protegir-les contra creació, modificació o eliminació. Requerir mantindre una història lineal. No permetre publicacions forçades (push --force). Requerir que les comprovacions automàtiques s'hagen completat satisfactòriament. Requerir que la fusió es realitze mitjançant una PR. En aquest cas, es poden configurar altres opcions com: Requerir que la branca estiga actualitzada amb la branca de destí. Requerir revisió d'un nombre mínim de revisors. Requerir una resolució dels conflictes abans de la fusió. Figura 6. Protecció de branques 📌 Aquest document pot quedar desactualitzat després d’imprimir-lo. Pots consultar la versió més recent a la pàgina web. 🌿 Abans d’imprimir aquest document, considera si és realment necessari. Redueix el consum de paper i ajuda a protegir el nostre entorn.

CC BY-NC-SA 4.0 (Reconeixement - NoComercial - CompartirIgual) 🅭 Joan Puigcerver Ibáñez