Ara que el nostre compte està configurat, passem per alguns detalls que poden ser útils per ajudar-vos a contribuir a un projecte existent.
Si voleu contribuir a un projecte existent al qual no teniu accés de push, podeu “bifurcar” el projecte. Quan “bifurqueu” un projecte, GitHub farà una còpia del projecte que és totalment vostra; viu al vostre espai de noms, i podeu fer push a ell.
|
Note
|
Històricament, el terme “bifurcació” ha tingut una connotació una mica negativa, significant que algú va prendre un projecte de codi obert en una direcció diferent, de vegades creant un projecte competidor i dividint els contribuïdors. A GitHub, una “bifurcació” és simplement el mateix projecte al vostre propi espai de noms, permetent-vos fer canvis a un projecte públicament com a manera de contribuir de manera més oberta. |
D’aquesta manera, els projectes no han de preocupar-se per afegir usuaris com a col·laboradors per donar-los accés de push. Les persones poden bifurcar un projecte, fer push a ell, i contribuir amb els seus canvis tornant al repositori original creant el que s’anomena una Pull Request, que cobrirem a continuació. Això obre un fil de discussió amb revisió de codi, i el propietari i el contribuïdor poden comunicar-se sobre el canvi fins que el propietari estigui content amb ell, moment en què el propietari pot fusionar-lo.
Per bifurcar un projecte, visiteu la pàgina del projecte i feu clic al botó “Fork” a la part superior dreta de la pàgina.
Després de uns segons, us portarà a la vostra nova pàgina del projecte, amb la vostra pròpia còpia editable del codi.
GitHub està dissenyat al voltant d’un flux de treball de col·laboració particular, centrat en les Pull Requests. Aquest flux funciona tant si esteu col·laborant amb un equip molt unit en un únic repositori compartit, com amb una empresa distribuïda globalment o una xarxa d’estranys que contribueixen a un projecte a través de desenes de bifurcacions. Està centrat en el flux de treball de ch03-git-branching.asc cobert a ch03-git-branching.asc.
Així és com generalment funciona:
-
Bifurqueu el projecte.
-
Creeu una branca temàtica des de
master. -
Feu alguns commits per millorar el projecte.
-
Pugeu aquesta branca al vostre projecte de GitHub.
-
Obriu una Pull Request a GitHub.
-
Discutiu, i opcionalment continueu fent commits.
-
El propietari del projecte fusiona o tanca la Pull Request.
-
Sincronitzeu el
masteractualitzat de tornada a la vostra bifurcació.
Això és bàsicament el flux de treball de l’Integration Manager cobert a ch05-distributed-git.asc, però en lloc d’utilitzar el correu electrònic per comunicar i revisar canvis, els equips utilitzen les eines basades en web de GitHub.
Passem per un exemple de proposar un canvi a un projecte de codi obert allotjat a GitHub utilitzant aquest flux.
|
Tip
|
Podeu utilitzar l’eina oficial GitHub CLI en lloc de la interfície web de GitHub per a la majoria de coses. L’eina es pot utilitzar en sistemes Windows, macOS i Linux. Aneu a la pàgina principal de GitHub CLI per a instruccions d’instal·lació i el manual. |
Tony està buscant codi per executar al seu microcontrolador programable Arduino i ha trobat un gran fitxer de programa a GitHub a https://github.com/schacon/blink.
L’únic problema és que la velocitat de parpelleig és massa ràpida. Pensem que és molt millor esperar 3 segons en lloc d'1 entre cada canvi d’estat. Així que millorem el programa i el enviem de tornada al projecte com a canvi proposat.
Primer, fem clic al botó 'Fork' com s’ha esmentat anteriorment per obtenir la nostra pròpia còpia del projecte.
El nostre nom d’usuari aquí és “tonychacon” així que la nostra còpia d’aquest projecte està a https://github.com/tonychacon/blink i és allà on podem editar-lo.
El clonarem localment, crearem una branca temàtica, farem el canvi de codi i finalment pujarem aquest canvi de tornada a GitHub.
$ git clone https://github.com/tonychacon/blink (1)
Cloning into 'blink'...
$ cd blink
$ git checkout -b slow-blink (2)
Switched to a new branch 'slow-blink'
$ sed -i '' 's/1000/3000/' blink.ino (macOS) (3)
# If you're on a Linux system, do this instead:
# $ sed -i 's/1000/3000/' blink.ino (3)
$ git diff --word-diff (4)
diff --git a/blink.ino b/blink.ino
index 15b9911..a6cc5a5 100644
--- a/blink.ino
+++ b/blink.ino
@@ -18,7 +18,7 @@ void setup() {
// la rutina de bucle s'executa una i una altra vegada per sempre:
void loop() {
digitalWrite(led, HIGH); // encén el LED (HIGH és el nivell de voltatge)
[-delay(1000);-]{+delay(3000);+} // espera un segon
digitalWrite(led, LOW); // apaga el LED fent el voltatge LOW
[-delay(1000);-]{+delay(3000);+} // espera un segon
}
$ git commit -a -m 'Change delay to 3 seconds' (5)
[slow-blink 5ca509d] Change delay to 3 seconds
1 file changed, 2 insertions(+), 2 deletions(-)
$ git push origin slow-blink (6)
Username for 'https://github.com': tonychacon
Password for 'https://tonychacon@github.com':
Counting objects: 5, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 340 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To https://github.com/tonychacon/blink
* [new branch] slow-blink -> slow-blink-
Clonem la nostra bifurcació del projecte localment.
-
Creem una branca temàtica descriptiva.
-
Fem el nostre canvi al codi.
-
Comprovem que el canvi és bo.
-
Confirmem el nostre canvi a la branca temàtica.
-
Pujem la nostra nova branca temàtica de tornada a la nostra bifurcació de GitHub.
Ara, si tornem a la nostra bifurcació a GitHub, podem veure que GitHub ha notat que hem pujat una nova branca temàtica i ens presenta un gran botó verd per revisar els nostres canvis i obrir una Pull Request al projecte original.
També podeu anar a la pàgina “Branches” a https://github.com/<user>/<project>/branches per localitzar la vostra branca i obrir una nova Pull Request des d’allà.
Si fem clic a aquest botó verd, veurem una pantalla que ens demana donar a la nostra Pull Request un títol i una descripció. Gairebé sempre val la pena posar-hi esforç, ja que una bona descripció ajuda el propietari del projecte original a determinar què esteu intentant fer, si els vostres canvis proposats són correctes, i si acceptar els canvis milloraria el projecte original.
També veiem una llista dels commits a la nostra branca temàtica que estan “ahead” de la branca master (en aquest cas, només un) i un diff unificat de tots els canvis que es faran si aquesta branca es fusiona pel propietari del projecte.
Quan feu clic al botó 'Create pull request' en aquesta pantalla, el propietari del projecte que heu bifurcat rebran una notificació que algú està suggerint un canvi i enllaçarà a una pàgina que té tota aquesta informació.
|
Note
|
Tot i que les Pull Requests s’utilitzen comunament per a projectes públics com aquest quan el contribuïdor té un canvi complet llest per fer-se, també s’utilitzen sovint en projectes interns al principi del cicle de desenvolupament. Com que podeu seguir pujant a la branca temàtica fins i tot després que s’obri la Pull Request, sovint s’obre aviat i s’utilitza com a manera d’iterar en el treball com a equip dins d’un context, en lloc d’obrir-se al final del procés. |
En aquest punt, el propietari del projecte pot mirar el canvi suggerit i fusionar-lo, rebutjar-lo o comentar-lo. Digueu que li agrada la idea, però preferiria un temps una mica més llarg perquè la llum estigui apagada que encesa.
On aquesta conversa podria tenir lloc per correu electrònic als fluxos de treball presentats a ch05-distributed-git.asc, a GitHub això passa en línia. El propietari del projecte pot revisar el diff unificat i deixar un comentari fent clic a qualsevol de les línies.
Un cop el mantenedor fa aquest comentari, la persona que va obrir la Pull Request (i de fet, qualsevol altra persona que estigui observant el repositori) rebran una notificació. Ho revisarem més endavant, però si tenia les notificacions per correu electrònic activades, Tony rebria un correu com aquest:
Qualsevol també pot deixar comentaris generals a la Pull Request. A Pàgina de discussió de la Pull Request podem veure un exemple del propietari del projecte comentant una línia de codi i després deixant un comentari general a la secció de discussió. Podeu veure que els comentaris del codi també es porten a la conversa.
Ara el contribuïdor pot veure el que ha de fer per obtenir el seu canvi acceptat. Afortunadament això és molt senzill. On per correu electrònic podríeu haver de re-fer la vostra sèrie i reenviar-la a la llista de correu, amb GitHub simplement confirmeu a la branca temàtica una altra vegada i pugeu, el que actualitzarà automàticament la Pull Request. A Pull Request final també podeu veure que el vell comentari del codi s’ha col·lapsat a la Pull Request actualitzada, ja que es va fer a una línia que des de llavors ha estat canviada.
Afegir commits a una Pull Request existent no activa una notificació, així que un cop Tony ha pujat les seves correccions decideix deixar un comentari per informar al propietari del projecte que ha fet el canvi sol·licitat.
Una cosa interessant a notar és que si feu clic a la pestanya “Files Changed” en aquesta Pull Request, obtindreu el diff “unified” — és a dir, la diferència agregada total que s’introduiria a la vostra branca principal si aquesta branca temàtica es fusionés.
En termes de git diff, bàsicament us mostra automàticament git diff master…<branch> per a la branca en què es basa aquesta Pull Request.
Consulteu ch05-distributed-git.asc per obtenir més informació sobre aquest tipus de diff.
L’altra cosa que notareu és que GitHub comprova si la Pull Request es fusiona netament i proporciona un botó per fer la fusió per a vosaltres al servidor. Aquest botó només apareix si teniu accés d’escriptura al repositori i una fusió trivial és possible. Si feu clic a GitHub realitzarà una fusió “non-fast-forward”, cosa que significa que fins i tot si la fusió podria ser un fast-forward, encara crearà un commit de fusió.
Si ho preferiu, podeu simplement baixar la branca i fusionar-la localment.
Si fusiona aquesta branca a la branca master i la puja a GitHub, la Pull Request es tancarà automàticament.
Aquest és el flux de treball bàsic que utilitzen la majoria de projectes de GitHub. Es creen branques temàtiques, s’obren Pull Requests sobre elles, s’inicia una discussió, possiblement es fa més feina a la branca i finalment la sol·licitud es tanca o es fusiona.
|
Note
|
No només bifurcacions
És important tenir en compte que també podeu obrir una Pull Request entre dues branques del mateix repositori.
Si esteu treballant en una característica amb algú i tots dos teniu accés d’escriptura al projecte, podeu pujar una branca temàtica al repositori i obrir una Pull Request a la branca |
Ara que hem cobert els fonaments de contribuir a un projecte a GitHub, passem per alguns consells i trucs interessants sobre les Pull Requests per tal que pugueu ser més efectius en utilitzar-les.
És important entendre que molts projectes no pensen realment en les Pull Requests com a cues de patches perfectes que s’haurien d’aplicar netament en ordre, com la majoria de projectes basats en llistes de correu pensen en les contribucions de sèries de patches. La majoria de projectes de GitHub pensen en les branques de Pull Request com a converses iteratives al voltant d’un canvi proposat, culminant en un diff unificat que s’aplica fusionant.
Aquesta és una distinció important, perquè generalment el canvi es suggereix abans que el codi es pensi que és perfecte, cosa que és molt més rara amb les contribucions de sèries de patches basades en llistes de correu. Això permet una conversa més primerenca amb els mantenedors perquè arribar a la solució adequada sigui més un esforç comunitari. Quan el codi es proposa amb una Pull Request i els mantenedors o la comunitat suggereixen un canvi, la sèrie de patches generalment no es re-fer, sinó que la diferència es puja com un nou commit a la branca, movent la conversa endavant amb el context de la feina prèvia intacte.
Per exemple, si torneu enrere i mireu de nou Pull Request final, notareu que el contribuïdor no va rebasejar el seu commit i enviar una altra Pull Request. En lloc d’això, van afegir nous commits i els van pujar a la branca existent. D’aquesta manera, si torneu enrere i mireu aquesta Pull Request en el futur, podeu trobar fàcilment tot el context de per què es van prendre decisions. Fer clic al botó “Merge” al lloc proposadament crea un commit de fusió que referencia la Pull Request perquè sigui fàcil tornar enrere i investigar la conversa original si és necessari.
Si la vostra Pull Request queda desactualitzada o d’una altra manera no es fusiona netament, voldreu corregir-la perquè el mantenedor pugui fusionar-la fàcilment. GitHub ho comprovarà per a vosaltres i us ho farà saber a la part inferior de cada Pull Request si la fusió és trivial o no.
Si veieu alguna cosa com La Pull Request no es fusiona netament, voldreu corregir la vostra branca perquè es torni verda i el mantenedor no hagi de fer feina extra.
Teniu dues opcions principals per fer això.
Podeu rebasejar la vostra branca sobre el que sigui la branca objectiu (normalment la branca master del repositori que heu bifurcat), o podeu fusionar la branca objectiu a la vostra branca.
La majoria de desenvolupadors a GitHub triaran de fer aquest últim, pels mateixos motius que acabem de veure a la secció anterior. El que importa és la història i la fusió final, així que rebasejar no us dona gaire cosa més que una història una mica més neta i en canvi és molt més difícil i propens a errors.
Si voleu fusionar la branca objectiu per fer que la vostra Pull Request es pugui fusionar, afegiríeu el repositori original com a nou remot, baixaríeu d’ell, fusionaríeu la branca principal d’aquest repositori a la vostra branca temàtica, corregiríeu qualsevol problema i finalment la pujaríeu de tornada a la mateixa branca on vau obrir la Pull Request.
Per exemple, diguem que a l’exemple de “tonychacon” que estàvem utilitzant abans, l’autor original va fer un canvi que crearia un conflicte a la Pull Request. Passem per aquests passos.
$ git remote add upstream https://github.com/schacon/blink (1)
$ git fetch upstream (2)
remote: Counting objects: 3, done.
remote: Compressing objects: 100% (3/3), done.
Unpacking objects: 100% (3/3), done.
remote: Total 3 (delta 0), reused 0 (delta 0)
From https://github.com/schacon/blink
* [new branch] master -> upstream/master
$ git merge upstream/master (3)
Auto-merging blink.ino
CONFLICT (content): Merge conflict in blink.ino
Automatic merge failed; fix conflicts and then commit the result.
$ vim blink.ino (4)
$ git add blink.ino
$ git commit
[slow-blink 3c8d735] Merge remote-tracking branch 'upstream/master' \
into slower-blink
$ git push origin slow-blink (5)
Counting objects: 6, done.
Delta compression using up to 8 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 682 bytes | 0 bytes/s, done.
Total 6 (delta 2), reused 0 (delta 0)
To https://github.com/tonychacon/blink
ef4725c..3c8d735 slower-blink -> slow-blink-
Afegiu el repositori original com a remot anomenat
upstream. -
Obteniu la feina més nova d’aquest remot.
-
Fusionar la branca principal d’aquest repositori a la vostra branca temàtica.
-
Corregiu el conflicte que es va produir.
-
Pugeu de tornada a la mateixa branca temàtica.
Un cop feu això, la Pull Request s’actualitzarà automàticament i es tornarà a comprovar per veure si es fusiona netament.
Una de les coses bones de Git és que podeu fer això contínuament. Si teniu un projecte de molt temps, podeu fusionar fàcilment des de la branca objectiu una i altra vegada i només haver de tractar amb els conflictes que han sorgit des de l’última vegada que vau fusionar, fent el procés molt manejable.
Si absolutament voleu rebasejar la branca per netejar-la, certament podeu fer-ho, però s’aconsella molt no fer push forçat sobre la branca en què la Pull Request ja està oberta. Si altres persones l’han baixat i hi han fet més feina, us trobareu amb tots els problemes esbossats a ch03-git-branching.asc. En lloc d’això, pugeu la branca rebasejada a una nova branca a GitHub i obriu una nova Pull Request referint-vos a l’antiga, després tanqueu l’original.
La vostra propera pregunta podria ser “Com puc referenciar l’antiga Pull Request?”. Resulta que hi ha moltes, moltes maneres de referenciar altres coses gairebé a qualsevol lloc on podeu escriure a GitHub.
Comencem amb com fer referència creuada a una altra Pull Request o un Issue.
Totes les Pull Requests i Issues se’ls assignen números i són únics dins del projecte.
Per exemple, no podeu tenir la Pull Request #3 i l’Issue #3.
Si voleu referenciar qualsevol Pull Request o Issue des de qualsevol altre, simplement podeu posar #<num> en qualsevol comentari o descripció.
També podeu ser més específics si l’Issue o Pull request viu en un altre lloc; escriviu username#<num> si us esteu referint a un Issue o Pull Request en una bifurcació del repositori en què esteu, o username/repo#<num> per referenciar alguna cosa en un altre repositori.
Mirem un exemple. Diguem que hem rebasejat la branca de l’exemple anterior, hem creat una nova pull request per a ella, i ara volem referenciar l’antiga pull request des de la nova. També volem referenciar un issue a la bifurcació del repositori i un issue en un projecte completament diferent. Podem omplir la descripció com Referències creuades en una Pull Request.
Quan enviem aquesta pull request, veurem tot això renderitzat com Referències creuades renderitzades en una Pull Request.
Noteu que l’URL complet de GitHub que hi vam posar s’ha acurtat només a la informació necessària.
Ara, si Tony torna enrere i tanca la Pull Request original, podem veure que en mencionar-la a la nova, GitHub ha creat automàticament un esdeveniment de trackback a la línia de temps de la Pull Request. Això significa que qualsevol que visiti aquesta Pull Request i vegi que està tancada pot enllaçar fàcilment a la que la va substituir. L’enllaç es veurà com Enllaç de tornada a la nova Pull Request a la línia de temps de la Pull Request tancada.
A més dels números d’issue, també podeu referenciar un commit específic per SHA-1. Heu d’especificar un SHA-1 complet de 40 caràcters, però si GitHub veu això en un comentari, enllaçarà directament al commit. Un altre cop, podeu referenciar commits en bifurcacions o altres repositoris de la mateixa manera que ho vau fer amb els issues.
Enllaçar a altres Issues és només el començament del que podeu fer amb gairebé qualsevol caixa de text a GitHub. A les descripcions d’Issues i Pull Requests, comentaris, comentaris de codi i més, podeu utilitzar el que s’anomena “GitHub Flavored Markdown”. Markdown és com escriure en text pla però que es renderitza de manera rica.
Consulteu Un exemple de GitHub Flavored Markdown com s’escriu i com es renderitza per a un exemple de com es poden escriure els comentaris o el text i després renderitzar-se utilitzant Markdown.
La versió de GitHub de Markdown afegeix més coses que podeu fer més enllà de la sintaxi bàsica de Markdown. Aquestes poden ser realment útils quan es creen comentaris o descripcions útils de Pull Request o Issue.
La primera característica realment útil de Markdown específica de GitHub, especialment per a l’ús en Pull Requests, és la Llista de Tasques. Una llista de tasques és una llista de caselles de verificació de coses que voleu fer. Posar-les en un Issue o Pull Request normalment indica coses que voleu fer abans de considerar l’element complet.
Podeu crear una llista de tasques així:
- [X] Escriure el codi
- [ ] Escriure totes les proves
- [ ] Documentar el codiSi incloem això a la descripció del nostre Pull Request o Issue, el veureu renderitzat com Llistes de tasques renderitzades en un comentari de Markdown.
Això s’utilitza sovint en Pull Requests per indicar tot el que us agradaria fer a la branca abans que la Pull Request estigui llesta per fusionar. La part realment genial és que simplement podeu fer clic a les caselles de verificació per actualitzar el comentari — no heu d’editar el Markdown directament per marcar les tasques com a fetes.
A més, GitHub buscarà llistes de tasques als vostres Issues i Pull Requests i les mostrarà com a metadades a les pàgines que les llisten. Per exemple, si teniu una Pull Request amb tasques i mireu la pàgina de visió general de totes les Pull Requests, podeu veure quant s’ha fet. Això ajuda les persones a desglossar les Pull Requests en subtasques i ajuda altres persones a fer un seguiment del progrés de la branca. Podeu veure un exemple d’això a Resum de la llista de tasques a la llista de Pull Request.
Aquestes són increïblement útils quan obriu una Pull Request aviat i l’utilitzeu per fer un seguiment del vostre progrés a través de la implementació de la característica.
També podeu afegir fragments de codi als comentaris. Això és especialment útil si voleu presentar alguna cosa que podríeu provar de fer abans d’implementar-la realment com a commit a la vostra branca. Això també s’utilitza sovint per afegir codi d’exemple del que no funciona o del que aquesta Pull Request podria implementar.
Per afegir un fragment de codi heu de “tancar-lo” entre accents graves.
```java
for(int i=0 ; i < 5 ; i++)
{
System.out.println("i is : " + i);
}
```Si afegeixes un nom de llenguatge com ho hem fet amb 'java', GitHub també intentarà ressaltar la sintaxi del fragment. En el cas de l’exemple anterior, es renderitzaria com Exemple de codi tancat renderitzat.
Si estàs responent a una petita part d’un comentari llarg, pots citar selectivament el fragment precedint les línies amb el caràcter >.
De fet, això és tan comú i útil que hi ha una drecera de teclat per fer-ho.
Si destaques text en un comentari al qual vols respondre directament i prems la tecla r, es citarà automàticament al quadre de comentaris.
Les cites es veuran així:
> Sigui més noble a la ment sofrir
> Els dards i fletxes de la fortuna cruel,
Quina mida tenen aquests dards i aquestes fletxes?Un cop renderitzat, el comentari es veurà com Exemple de citació renderitzada.
