Ara que estem còmodes contribuint a un projecte, mirem l’altre costat: crear, mantenir i administrar el vostre propi projecte.
Creem un nou repositori per compartir el codi del nostre projecte. Comenceu fent clic al botó “New repository” al costat dret del tauler, o des del botó + a la barra d’eines superior al costat del vostre nom d’usuari com es veu a El menú desplegable “New repository”.
Això us porta al formulari “new repository”:
Tot el que realment heu de fer aquí és proporcionar un nom de projecte; la resta dels camps són completament opcionals.
Per ara, simplement feu clic al botó “Create Repository”, i ja teniu un nou repositori a GitHub, anomenat <usuari>/<nom_projecte>.
Com que encara no hi ha cap codi, GitHub us mostrarà instruccions sobre com crear un repositori Git completament nou, o connectar un projecte Git existent. No ens estendrem aquí; si necessiteu un repàs, consulteu ch02-git-basics-chapter.asc.
Ara que el vostre projecte està allotjat a GitHub, podeu donar l’URL a qualsevol persona amb qui vulgueu compartir el vostre projecte.
Cada projecte a GitHub és accessible a través d’HTTPS com https://github.com/<usuari>/<nom_projecte>, i a través de SSH com git@github.com:<usuari>/<nom_projecte>.
Git pot obtenir i pujar a ambdues d’aquestes URLs, però estan controlades per accés basant-se en les credencials de l’usuari que s’hi connecta.
|
Note
|
Sovint és preferible compartir l’URL basada en HTTPS per a un projecte públic, ja que l’usuari no ha de tenir un compte de GitHub per accedir-hi per clonar-lo. Els usuaris haurien de tenir un compte i una clau SSH pujada per accedir al vostre projecte si els doneu l’URL SSH. L’HTTPS també és exactament la mateixa URL que enganxarien en un navegador per veure el projecte allà. |
Si esteu treballant amb altres persones a les quals voleu donar accés de commit, heu d’afegir-les com a “col·laboradors”. Si Ben, Jeff i Louise s’han registrat tots a GitHub, i voleu donar-los accés de push al vostre repositori, podeu afegir-los al vostre projecte. Fer-ho els donarà accés de “push”, el que significa que tenen accés de lectura i escriptura al projecte i al repositori Git.
Feu clic a l’enllaç “Settings” a la part inferior de la barra lateral dreta.
Llavors seleccioneu “Col·laboradors” del menú del costat esquerre. Llavors, simplement escriviu un nom d’usuari a la caixa, i feu clic a “Add collaborator”. Podeu repetir això tantes vegades com vulgueu per donar accés a tots els que vulgueu. Si necessiteu revocar l’accés, simplement feu clic a la “X” al costat dret de la seva fila.
Ara que teniu un projecte amb algun codi i fins i tot uns quants col·laboradors que també tenen accés de push, passem a veure què fer quan rebem una Pull Request.
Les Pull Requests poden venir d’una branca en una bifurcació del vostre repositori o poden venir d’una altra branca en el mateix repositori. L’única diferència és que les que estan en una bifurcació sovint són de persones on no podeu fer push a la seva branca i elles no poden fer push a la vostra, mentre que amb les Pull Requests internes generalment ambdues parts poden accedir a la branca.
Per a aquests exemples, suposem que sou “tonychacon” i heu creat un nou projecte de codi Arduino anomenat “fade”.
Algué apareix i fa un canvi al vostre codi i us envia una Pull Request. Hauríeu de rebre un correu electrònic notificant-vos sobre la nova Pull Request i hauria de semblar-se a Notificació per correu electrònic d’una nova Pull Request.
Hi ha algunes coses a notar sobre aquest correu electrònic. Us donarà un petit diffstat — una llista de fitxers que han canviat a la Pull Request i en quina quantitat. Us dona un enllaç a la Pull Request a GitHub. També us dona algunes URLs que podeu utilitzar des de la línia d’ordres.
Si noteu la línia que diu git pull <url> patch-1, aquesta és una manera senzilla de fusionar una branca remota sense haver d’afegir un remot.
Ho vam veure ràpidament a ch05-distributed-git.asc.
Si voleu, podeu crear i canviar a una branca temàtica i llavors executar aquesta ordre per fusionar els canvis de la Pull Request.
Les altres URLs interessants són les .diff i .patch, que, com podeu endevinar, proporcionen versions de diff unificat i patch de la Pull Request.
Tècnicament podeu fusionar el treball de la Pull Request amb alguna cosa com això:
$ curl https://github.com/tonychacon/fade/pull/1.patch | git amCom vam cobrir a ch06-github.asc, ara podeu tenir una conversa amb la persona que va obrir la Pull Request. Podeu comentar línies específiques de codi, comentar commits sencers o comentar tota la Pull Request, utilitzant GitHub Flavored Markdown a tot arreu.
Cada vegada que algú altre comenta a la Pull Request continuareu rebent notificacions per correu electrònic perquè sabeu que hi ha activitat. Cada un tindrà un enllaç a la Pull Request on està passant l’activitat i també podeu respondre directament al correu per comentar al fil de la Pull Request.
Un cop el codi està en un lloc que us agrada i voleu fusionar-lo, podeu baixar el codi i fusionar-lo localment, ja sigui amb la sintaxi git pull <url> <branch> que vam veure abans, o afegint la bifurcació com a remot i baixant i fusionant.
Si la fusió és trivial, també podeu simplement prémer el botó “Merge” al lloc web de GitHub. Això farà una fusió “non-fast-forward”, creant un commit de fusió fins i tot si una fusió fast-forward fos possible. Això significa que no importa què, cada vegada que premeu el botó de fusió, es crea un commit de fusió. Com podeu veure a Botó de fusió i instruccions per fusionar una Pull Request manualment, GitHub us dona tota aquesta informació si feu clic a l’enllaç d’ajuda.
Si decideu que no voleu fusionar-la, també podeu simplement tancar la Pull Request i la persona que l’ha oberta serà notificada.
Si esteu tractant amb moltes Pull Requests i no voleu afegir un munt de remots o fer pulls d’una sola vegada cada vegada, hi ha un truc molt útil que GitHub us permet fer. Això és una mica un truc avançat i ho cobrirem una mica més a ch10-git-internals.asc, però pot ser bastant útil.
GitHub realment anuncia les branques de Pull Request per a un repositori com a una mena de pseudo-branques al servidor. Per defecte no les obteniu quan cloneu, però estan allà d’una manera una mica oculta i podeu accedir-hi bastant fàcilment.
Per demostrar això, utilitzarem una ordre de baix nivell (sovint referida com una ordre de “plomería”, de la qual llegirem més a ch10-git-internals.asc) anomenada ls-remote.
Aquesta ordre generalment no s’utilitza en les operacions diàries de Git però és útil per mostrar-nos quines referències estan presents al servidor.
Si executem aquesta ordre contra el repositori “blink” que estàvem utilitzant abans, obtindrem una llista de totes les branques, etiquetes i altres referències al repositori.
$ git ls-remote https://github.com/schacon/blink
10d539600d86723087810ec636870a504f4fee4d HEAD
10d539600d86723087810ec636870a504f4fee4d refs/heads/master
6a83107c62950be9453aac297bb0193fd743cd6e refs/pull/1/head
afe83c2d1a70674c9505cc1d8b7d380d5e076ed3 refs/pull/1/merge
3c8d735ee16296c242be7a9742ebfbc2665adec1 refs/pull/2/head
15c9f4f80973a2758462ab2066b6ad9fe8dcf03d refs/pull/2/merge
a5a7751a33b7e86c5e9bb07b26001bb17d775d1a refs/pull/4/head
31a45fc257e8433c8d8804e3e848cf61c9d3166c refs/pull/4/mergePer descomptat, si esteu al vostre repositori i executeu git ls-remote origin o qualsevol remot que vulgueu comprovar, us mostrarà alguna cosa similar a això.
Si el repositori està a GitHub i teniu qualsevol Pull Request que s’hagi obert, obtindreu aquestes referències que estan prefixades amb refs/pull/.
Aquestes són bàsicament branques, però com que no estan sota refs/heads/ no les obteniu normalment quan cloneu o baixeu del servidor — el procés de baixada les ignora normalment.
Hi ha dues referències per Pull Request - la que acaba en /head apunta exactament al mateix commit que l’últim commit a la branca de la Pull Request.
Així que si algú obre una Pull Request al nostre repositori i la seva branca es diu bug-fix i apunta al commit a5a775, llavors al nostre repositori no tindrem una branca bug-fix (ja que això està a la seva bifurcació), però sí tindrem pull/<pr#>/head que apunta a a5a775.
Això significa que podem baixar fàcilment cada branca de Pull Request d’una vegada sense haver d’afegir un munt de remots.
Ara, podeu fer alguna cosa com baixar la referència directament.
$ git fetch origin refs/pull/958/head
From https://github.com/libgit2/libgit2
* branch refs/pull/958/head -> FETCH_HEADAixò diu a Git, “Connecta’t al remot origin, i baixa la ref anomenada refs/pull/958/head.”
Git obeeix feliçment, i baixa tot el necessari per construir aquesta ref, i posa un punter al commit que voleu sota .git/FETCH_HEAD.
Podeu seguir això amb git merge FETCH_HEAD en una branca on vulgueu provar-la, però el missatge de commit de fusió sembla una mica estrany.
A més, si esteu revisant moltes pull requests, això es torna tediós.
També hi ha una manera de baixar totes les pull requests, i mantenir-les actualitzades cada vegada que us connecteu al remot.
Obriu .git/config al vostre editor preferit, i busqueu el remot origin.
Hauria de semblar-se una mica a això:
[remote "origin"]
url = https://github.com/libgit2/libgit2
fetch = +refs/heads/*:refs/remotes/origin/*Aquella línia que comença amb fetch = és una “refspec.”
És una manera de mapear noms al remot amb noms al vostre directori local .git.
Aquesta en particular diu a Git, "les coses al remot que estan sota refs/heads haurien d’anar al meu repositori local sota `refs/remotes/origin`".
Podeu modificar aquesta secció per afegir una altra refspec:
[remote "origin"]
url = https://github.com/libgit2/libgit2.git
fetch = +refs/heads/*:refs/remotes/origin/*
fetch = +refs/pull/*/head:refs/remotes/origin/pr/*Aquella última línia diu a Git, “Totes les refs que semblen refs/pull/123/head s’haurien d’emmagatzemar localment com refs/remotes/origin/pr/123.”
Ara, si deseu aquest fitxer, i feu un git fetch:
$ git fetch
# …
* [new ref] refs/pull/1/head -> origin/pr/1
* [new ref] refs/pull/2/head -> origin/pr/2
* [new ref] refs/pull/4/head -> origin/pr/4
# …Ara totes les pull requests remotes estan representades localment amb refs que actuen molt com branques de seguiment; són de només lectura, i s’actualitzen quan feu un fetch. Això fa que sigui super fàcil provar el codi d’una pull request localment:
$ git checkout pr/2
Checking out files: 100% (3769/3769), done.
Branch pr/2 set up to track remote branch pr/2 from origin.
Switched to a new branch 'pr/2'Els més aguts entre vosaltres notaran el head al final de la part remota de la refspec.
També hi ha una ref refs/pull/#/merge al costat de GitHub, que representa el commit que resultaria si premeu el botó “merge” al lloc web.
Això us pot permetre provar la fusió abans fins i tot de prémer el botó.
No només podeu obrir Pull Requests que tenen com a objectiu la branca principal o master, sinó que realment podeu obrir una Pull Request que tingui com a objectiu qualsevol branca de la xarxa.
De fet, fins i tot podeu tenir com a objectiu una altra Pull Request.
Si veieu una Pull Request que va en la direcció correcta i teniu una idea per a un canvi que depèn d’ella o no esteu segurs si és una bona idea, o simplement no teniu accés de push a la branca objectiu, podeu obrir una Pull Request directament a ella.
Quan aneu a obrir una Pull Request, hi ha una caixa a la part superior de la pàgina que especifica a quina branca esteu sol·licitant fer pull i de quina esteu sol·licitant fer pull. Si feu clic al botó “Edit” a la dreta d’aquesta caixa podeu canviar no només les branques sinó també quina bifurcació.
Aquí podeu especificar bastant fàcilment fusionar la vostra nova branca en una altra Pull Request o en una altra bifurcació del projecte.
GitHub també té un sistema de notificacions bastant bo incorporat que pot ser útil quan teniu preguntes o necessiteu retroalimentació d’individus o equips específics.
En qualsevol comentari podeu començar a escriure un caràcter @ i començarà a autocompletar amb els noms i noms d’usuari de persones que són col·laboradors o contribuïdors al projecte.
També podeu esmentar un usuari que no està en aquell menú desplegable, però sovint l’autocompletador pot fer-ho més ràpid.
Un cop publiqueu un comentari amb una esment d’usuari, aquell usuari serà notificat. Això significa que això pot ser una manera realment efectiva de portar persones a converses en lloc de fer que les sondegin. Molt sovint a les Pull Requests a GitHub, les persones porten altres persones dels seus equips o de la seva empresa per revisar un Issue o Pull Request.
Si algú és esmentat en una Pull Request o Issue, serà “subscrit” a aquesta i continuarà rebent notificacions cada vegada que hi hagi alguna activitat. També esteu subscrit a alguna cosa si l’heu oberta, si esteu observant el repositori o si comenteu alguna cosa. Si ja no voleu rebre notificacions, hi ha un botó “Unsubscribe” a la pàgina que podeu prémer per deixar de rebre actualitzacions.
Quan parlem de “notificacions” aquí respecte a GitHub, ens referim a una manera específica que GitHub intenta posar-se en contacte amb vosaltres quan passen esdeveniments i hi ha algunes maneres diferents que podeu configurar-les. Si aneu a la pestanya “Notification center” des de la pàgina de configuració, podeu veure algunes de les opcions que teniu.
Les dues opcions són rebre notificacions per “Email” i per “Web” i podeu triar qualsevol, cap o ambdues per quan participeu activament en coses i per a l’activitat en repositoris que esteu observant.
Les notificacions web només existeixen a GitHub i només les podeu comprovar a GitHub. Si teniu aquesta opció seleccionada a les vostres preferències i es dispara una notificació per a vosaltres, veureu un petit punt blau sobre la vostra icona de notificacions a la part superior de la vostra pantalla com es veu a Centre de notificacions.
Si feu clic a això, veureu una llista de tots els elements sobre els quals heu estat notificat, agrupats per projecte. Podeu filtrar les notificacions d’un projecte específic fent clic al seu nom a la barra lateral esquerra. També podeu reconèixer la notificació fent clic a la icona de marca de verificació al costat de qualsevol notificació, o reconèixer totes les notificacions d’un projecte fent clic a la marca de verificació a la part superior del grup. També hi ha un botó de silenci al costat de cada marca de verificació que podeu prémer per no rebre més notificacions sobre aquell element.
Totes aquestes eines són molt útils per gestionar un gran nombre de notificacions. Molts usuaris avançats de GitHub simplement desactivaran les notificacions per correu electrònic completament i gestionaran totes les seves notificacions a través d’aquesta pantalla.
Les notificacions per correu electrònic són l’altra manera com podeu gestionar les notificacions a través de GitHub. Si teniu això activat, rebreu correus electrònics per a cada notificació. Vam veure exemples d’això a [_email_notification] i Notificació per correu electrònic d’una nova Pull Request. Els correus electrònics també estaran encadenats correctament, el que és bo si esteu utilitzant un client de correu electrònic que gestioni encadenats.
També hi ha una quantitat considerable de metadades incrustades als encapçalaments dels correus electrònics que GitHub us envia, el que pot ser realment útil per configurar filtres i regles personalitzades.
Per exemple, si mirem els encapçalaments reals dels correus electrònics enviats a Tony al correu electrònic mostrat a Notificació per correu electrònic d’una nova Pull Request, veurem el següent entre la informació enviada:
To: tonychacon/fade <fade@noreply.github.com>
Message-ID: <tonychacon/fade/pull/1@github.com>
Subject: [fade] Wait longer to see the dimming effect better (#1)
X-GitHub-Recipient: tonychacon
List-ID: tonychacon/fade <fade.tonychacon.github.com>
List-Archive: https://github.com/tonychacon/fade
List-Post: <mailto:reply+i-4XXX@reply.github.com>
List-Unsubscribe: <mailto:unsub+i-XXX@reply.github.com>,...
X-GitHub-Recipient-Address: tchacon@example.comHi ha algunes coses interessants aquí.
Si voleu ressaltar o reenviar correus electrònics a aquest projecte en particular o fins i tot a una Pull Request, la informació al camp Message-ID us dona totes les dades en format <usuari>/<projecte>/<tipus>/<id>.
Si això fos un issue, per exemple, el camp <tipus> hauria estat “issues” en lloc de “pull”.
Els camps List-Post i List-Unsubscribe signifiquen que si teniu un client de correu que entén aquests, podeu publicar fàcilment a la llista o “Desubscrivir-se” del fil.
Això seria essencialment el mateix que prémer el botó “mute” a la versió web de la notificació o “Unsubscribe” a la pàgina de l’Issue o Pull Request en si.
També val la pena esmentar que si teniu tant les notificacions per correu electrònic com les notificacions web activades i llegiu la versió per correu electrònic de la notificació, la versió web també es marcarà com a llegida si teniu les imatges permetudes al vostre client de correu.
Hi ha un parell de fitxers especials que GitHub notarà si estan presents al vostre repositori.
El primer és el fitxer README, que pot ser de gairebé qualsevol format que GitHub reconeix com a prosa.
Per exemple, podria ser README, README.md, README.asciidoc, etc.
Si GitHub veu un fitxer README al vostre codi font, el renderitzarà a la pàgina de destinació del projecte.
Molts equips utilitzen aquest fitxer per contenir tota la informació rellevant del projecte per a algú que pugui ser nou al repositori o projecte. Això generalment inclou coses com:
-
Per a què és el projecte
-
Com configurar-lo i instal·lar-lo
-
Un exemple de com utilitzar-lo o posar-lo en marxa
-
La llicència sota la qual s’ofereix el projecte
-
Com contribuir-hi
Com que GitHub renderitzarà aquest fitxer, podeu incrustar imatges o enllaços per a una major facilitat de comprensió.
L’altre fitxer especial que GitHub reconeix és el fitxer CONTRIBUTING.
Si teniu un fitxer anomenat CONTRIBUTING amb qualsevol extensió de fitxer, GitHub mostrarà Obrir una Pull Request quan existeix un fitxer CONTRIBUTING quan algú comenci a obrir una Pull Request.
La idea aquí és que podeu especificar coses específiques que voleu o no voleu en una Pull Request enviada al vostre projecte. D’aquesta manera les persones poden llegir les directrius abans d’obrir la Pull Request.
Generalment no hi ha moltes coses administratives que podeu fer amb un sol projecte, però hi ha un parell d’elements que poden ser d’interès.
Si esteu utilitzant una branca diferent de “master” com a la vostra branca per defecte a la qual voleu que la gent obri Pull Requests o vegi per defecte, podeu canviar això a la pàgina de configuració del vostre repositori sota la pestanya “Options”.
Simplement canvieu la branca per defecte al menú desplegable i aquesta serà la branca per defecte per a totes les operacions principals des d’aleshores, incloent quina branca es comprova per defecte quan algú clona el repositori.
Si voleu transferir un projecte a un altre usuari o a una organització a GitHub, hi ha una opció “Transfer ownership” a la part inferior de la mateixa pestanya “Options” de la pàgina de configuració del vostre repositori que us permet fer això.
Això és útil si esteu abandonant un projecte i algú vol fer-se’n càrrec, o si el vostre projecte està creixent i voleu moure’l a una organització.
No només això mou el repositori juntament amb tots els seus observadors i estrelles a un altre lloc, sinó que també configura una redirecció des de la vostra URL al nou lloc. També redirigirà els clons i les baixades des de Git, no només les sol·licituds web.