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 d'incorporació de canvis (Pull Request o PR) és una petició per a incorporar canvis en una branca d'un repositori. Les PR es poden utilitzar per a: Integrar branques: incorporar els canvis d'una branca en una altra dins del mateix repositori. Integrar bifurcacions: incorporar els canvis d'una bifurcació (fork) en el repositori principal. Utilitzar PR aporta molts avantatges, com ara: Revisió de canvis: permet revisar els canvis abans d'integrar-los en el projecte. Debat de canvis: facilita el debat i la revisió conjunta dels canvis amb altres persones de l'equip o col·laboradores. Automatització de tasques: permet executar tasques automàtiques abans d'incorporar els canvis, com ara les 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 en els de codi obert, on les persones que mantenen el projecte poden revisar els canvis proposats per la comunitat. Exemple: Pull Requests a Material for MkDocs En el repositori Material for MkDocs hi ha moltes PR amb canvis per a millorar el tema o actualitzar la documentació. Figura 1. Exemple de Pull Requests en el repositori Material for MkDocs. Creació d'una Pull Request Per a crear una PR, cal accedir al teu fork o a la teua branca i fer clic en el botó Pull Request. En el procés de creació, cal seleccionar els repositoris i les branques associats 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: Títol: descripció breu dels canvis realitzats. Descripció: informació addicional sobre els canvis realitzats. Exemple: Creació d'una Pull Request Es crea una PR per a incorporar canvis nous a la documentació de Material for MkDocs, amb els valors següents: 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 creada la PR, es pot sol·licitar a altres persones que revisen els canvis i fer les modificacions necessàries fins que s'accepte. Les PR poden estar en quatre estats diferents: Esborrany (Draft): creada, però no finalitzada. Oberta (Open): en procés de revisió i a punt per a ser fusionada. Fusionada (Merged): acceptada i incorporada al repositori. Tancada (Closed): rebutjada o tancada sense incorporar-la. Enllaçar incidències a una Pull Request Quan es treballa en un projecte, les PR sovint estan relacionades amb incidències específiques. GitHub permet enllaçar-les de manera que, quan s'accepta la PR, les incidències es tanquen automàticament. A més, això millora la traçabilitat del desenvolupament i facilita el seguiment dels canvis realitzats per a resoldre les incidències. Les incidències es poden enllaçar a una PR de dues maneres: Apartat Development: des de l'apartat Development de la barra lateral de la pàgina. Paraules clau: escrivint en la descripció una paraula clau seguida del número de la incidència. Les paraules clau admeses són close, closes, closed, fix, fixes, fixed, resolve, resolves i resolved. Closes #10 On #10 és el número de la incidència que es vol enllaçar. Documentació oficial: Linking a pull request to an issue – GitHub Exemple: Incidència enllaçada a una PR La imatge següent mostra una PR en el repositori Material for MkDocs que referencia una incidència per a corregir la barra lateral en el navegador Firefox. Figura 3. Incidència enllaçada a una Pull Request. Incorporació d'una Pull Request Quan s'accepta una PR, els canvis s'incorporen en la branca de destí i la PR es marca com a fusionada. La incorporació es pot fer de tres maneres diferents: Crear un commit de fusió: es crea un commit nou 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 fa un Canvi de base (git rebase) de la branca de la PR respecte de la branca de destí i es fusiona mitjançant una Fusió directa. La fusió en un sol commit (squash) és útil per a mantindre una història de commits més clara, ordenada i concisa. Si cal 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 Les tècniques d'incorporació habilitades, entre altres opcions, es configuren en 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 del de les Estratègies de ramificació: simplement proporciona un mecanisme addicional per a revisar i incorporar canvis. El flux de treball pot ser el següent: En el mateix repositoriEn un fork ( codi obert) Crea una branca nova per a fer els canvis. Fes els canvis en la branca. Crea una PR per a incorporar els canvis en la branca principal o de desenvolupament. Revisa i debat els canvis amb les persones revisores. Actualitza la PR amb els canvis necessaris o amb l'estat més recent de la branca de destí. Incorpora els canvis al repositori original. Crea un fork del repositori principal. Clona el fork en el teu entorn de desenvolupament. Crea una branca per a fer els canvis. Fes els canvis en la branca. Publica la branca en el fork. Crea una PR per a incorporar els canvis del fork al repositori principal. Revisa i debat els canvis amb les persones revisores. Actualitza la PR amb els canvis necessaris o amb l'estat més recent de la branca de destí. Incorpora els canvis al repositori original. Sincronitza ( Sync) el fork amb els canvis nous del repositori original. Protecció de branques Per a evitar canvis no desitjats en les branques principals i problemes deguts a una mala aplicació de les Estratègies de ramificació, les branques importants (com main o develop) es poden protegir mitjançant conjunts de regles (Rulesets). Per a 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 a modificar la branca especificada, com ara: Protecció: protegir la branca contra la creació, la modificació o l'eliminació. Història lineal: obligar a mantindre una història lineal. Publicacions forçades: no permetre publicacions forçades (push --force). Comprovacions: obligar que les comprovacions automàtiques s'hagen completat satisfactòriament. Pull Request obligatòria: obligar que la fusió es faça mitjançant una PR. En aquest cas, es poden configurar altres opcions, com ara: Que la branca estiga actualitzada amb la branca de destí. Que la revise un nombre mínim de persones. Que es resolguen els 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