El gitlab del departament

El servei gitlab

El departament disposa d’un servei d’allotjament de repositoris git amb el sistema gitlab  que podeu trobar a https://gitlab.mat-apl.upc.edu/. A continuació una petita explicació de què és i per a què serveix.

Què és git?

git  és un sistema de control de versions distribuït que serveix per a seguir la pista dels canvis en fitxers informàtics i per a coordinar el desenvolupament d’aquests fitxers per un equip de col·laboradors. Va ser iniciat per Linus Torvald com a ajuda  al desenvolupament de Linux. A diferència d’altres sistemes cada col·labor té al seu ordinador una còpia íntegra del repositori. Tal com es diu a  How to master the art of git:

Here lies the core reason why version control software is so important. It enables you, the developer, to have a clear view of all changes, revisions and improvements ever done to the code base. In turn making it much easier to collaborate, download code to make edits, and upload changes to the repository

Resumint: Hi ha dues operacions importants per a un desenvolupador que git permet de fer amb facilitat:

  • Revertir: Vols poder desfer canvis que trenquen el teu codi amb seguretat.
  • Resseguir canvis: Vols saber perquè algú va escriure una peça determinada, o com parts del codi s’interrelacionen amb altres parts.

On trobar més informació

Hi ha diversos tutorials com ara aquest o bé How I git.

Quan estava escrivint aquesta entrada,  la musa m’ha visitat i he decidit escriure’n una analogia.

Què és gitlab i per què en tenim un?

Darrerament git s’ha fet més popular perquè hi companyies al núvol que ofereixen allotjament gratuït de repositoris en aquest sistema, com per exemple Github i Bitbucket. Com que aquests serveis imposen certes condicions, hem pensat que podria ser útil per al departament tenir un servei similar  basat en el sistema lliure gitlab.

 

Per a què pot servir?

L’objectiu original del control de versions és ajudar el desenvolupament de programari, (per exemple, recuperant versions prèvies en cas de falles catastròfiques) però es pot usar per a seguir la pista dels canvis de tota mena de fitxers. Ho mostraré amb dos exemples rellevants pel departament:

Migració des d’un altre sistema

Els que teniu repositoris de programari en altre sistema de control de versions podeu (probablement) migrar al git. Consulteu aquí per a fer la migració. Si veniu de Subversion també podeu seguir aquesta guia.

Cicle bàsic de treball

Normalment el que fas és (més o menys):

Suposem que tenim una repositori local de git al nostre ordinador. Això pot ser perquè hem indicat a git que tal directori estarà sota control de versions (git init) i després ho hem pujat al servidor gitlab, o perquè hem baixat del gitlab un repositori existent (git clone). El cicle de treball a partir d’aquí és així (Cadascú té les seves rutines però):

  1. Fem un git pull per a obtenir els canvis que altres  col·laboradors puguin haver fet fins al moment
  2. En aquesta fase és on esmercem la major part del temps: Treballem amb els fitxers locals tal com fèiem abans de tenir control de versions.
  3. Fem un git status per a veure què hem canviat
  4. Un git add  per a afegir els canvis que volem registrar
  5. Registrem-ho efectivament amb git commit . Val la pena parar-spensar un moment en un missatge que sigui prou informatiu. Penseu que al cap d’un dies (o mesos, o anys) tornarem a visitar aquest commit i agrairem que la descripció sigui bona.
  6. Si cal, tornem al pas 2.
  7. En acabar, fer un git push per tal que els altres col·laboradors puguin veure els teus canvis

Maneres de treballar en equip

  • Pel que fa al permís de lectura:
    • Repositori Private: Només el propietari ho pot veure
    • Repositori Internal: Els membres del departament ho poden veure
    • Repositori Public: Tothom ho pot veure
  • Pel que fa al permís d’escriptura:
    • Si només hi treballa una persona no cal fer res.
    • Si hi treballa un equip de col·laboradors, s’ha de dir qui té permis per modificar-ho (vegeu com afegir un usuari).
    • En un repositori internalpublic, qualsevol que ho pot veure pot fer una còpia propia del repositori, fer canvis en aquesta còpia i demanar que s’incorporin al principal (merge request) això s’explica al segon vídeo de l’exemple del reglament.

Un parell d’exemples

El cas del reglament

Explico com podria haver anat l’evolució de les esmenes del reglament d’un departament1

És un bon exemple perquè el reglament és un document en evolució pel qual volem tenir informació detallada de quins canvis s’han anat incorporant (així com quan i per qui s’han fet) i és una manera de fer transparent tot el procès de manera automàtica. En particular podrem:

  • Comparar dues versions per a veure exactament què ha canviat (git diff)
  • Podem saber qui ha introduït un canvi i en quin moment (git blame)
  • Podem tenir una visió completa de la història del document (git log)

A més, el concepte branca s’ajusta molt naturalment al procés d’esmenar el reglament.

Al primer vídeo veiem com es fa per a crear un nou repositori al servidor gitlab usant git  des d’un terminal de text.

Al segon vídeo veiem com algú pot fer una còpia personal (fork) d’un repositori, modificar-lo i demanar que els canvis s’afegeixin a la branca principal (merge request):

Claus ssh

Tot plegat és molt més fàcil si teniu un parell de claus ssh. És una mica de feina per posar-ho a punt però després t’estalvies de posar noms d’usuari i contrasenyes. Per a veure com fer-ho vegeu aquí.

El material docent d’una assignatura

En aquest exemple, suposem que partim de tenir el material d’una assignatura en una carpeta al nostre ordinador i que volem pujar-ho a un repositori gitlab per (entre altres coses) compartir-ho amb els companys. No tenim l’aplicació git de terminal, o sigui que usarem una que és una interfície gràfica anomenada Sourcetree .

El punt de partida és haver creat un repositori gitlab buit tal com s’ha explicat al video d’abans. També veiem com es poden baixar commits del servidor a local:

Ara ens posem en la pell d’un col·laborador que vol accedir al material de l’assignatura i només té el Sourcetree . Veurem com fer al video que segueix:

 

 

Una introducció (novel·lada) al control de versions distribuït

 

—Ja cal que t’espavilis: El senyor Esteve té una cadena de tendes de mobles i decoració molt important i tindràs molta responsabilitat. Ta mare m’ha encarregat que no et deixi de petja.

—Però que hauré de fer?

—Mira, al senyor Esteve li preocupa molt que els seus clients tinguin una experiència de compra idèntica. Per a assegurar que totes les seves tendes tenen el mateix aparador, les tendes tenen un Llibre2 on figura com ha de quedar cada expositor. Fixa’t: Aquest és el d’aquí:

la senyora Pepeta obrí un llibre molt gruixut que més aviat era un parell de tapes amb un munt de fulls de paper encolats uns sobre els altres i una pila de punts de llibre que sortien d’entre ells. A la pàgina de dalt, en Bernat pogué llegir un tros que deia:

Paret Sud estucada en blanc. Conté:

  • a 40 cm i a 150 cm d’altura: Una còpia de Sardanes a la font de Sant Roc  de Ramon Casas i Carbó, en marc  de fusta de faig envernissada de 200 x 150 cm. Passpartout blanc trencat de 2 cm;

La senyora Pepeta continuà:

—Aquest llibre està format per pàgines de registre que porten ja imprès a la capçalera un número de sèrie en vermell. Totes les tendes tenen fulls de registre en blanc per anar anotant canvis i cada pàgina té un número de sèrie únic. Fem servir aquests fulls per a anotar els canvis.

—I això ho hauré de fer? Com sabem quins canvis hi ha?

—A la nostra tenda, d’això s’en encarrega n’Albert que té molt bona memòria. Mira: Justament acaba d’arribar per a buscar els canvis d’avui.

n’Albert prengué el Llibre i es tragué de la butxaca un manyoc de retalls de paper d’embalar i un cap de llapis. Aleshores començà a voltar per l’aparador tot mormolant mentre rellegia el Llibre i escrivia en els retalls de paper (diff). Al final els deixà sobre la taula i marxà. En Bernat va poder llegir el de sobre:

  • a la paret sud, Sardanes a la font …  s’ha mogut  15 cm a la dreta

 

Llavors arribà l’encarregat i va preguntar:

—On és l’índex?

La senyora Pepeta li va portar la pila de retalls, l’encarregat se’ls va llegir, en va llençar un i els va tornar a la senyora Pepeta dient-li:

—Ja ho pot apuntar. Posi-hi: “Amb la nova remesa de cadires”

La dona s’afanyà a recollit l’índex i digué a en Bernat:

—Ara faré una nova entrada al Llibre (commit). Fixa’t-hi bé que algun dia et tocarà fer-ho a tu.

Agafà un nou full de la pila de fulls de registre en blanc  i començà a copiar-hi amb bona lletra els canvis de la pila de l’índex.

—S’ha d’anar posant tots els canvis que n’Albert ha vist per tal que es pugui després reproduir. Ara fixa’t que aquí on diu Provinent de: hi poso el número de sèrie del darrer full del Llibre, el que porta el punt de llibre blanc (HEAD).

En Bernat observà que, a més, a un lloc on deia Descripció: la dona hi escrigué “Amb la nova remesa de cadires”. Seguidament la senyora Pepeta encolà aquest full a sobre del que hi ha havia i mogué els punts de llibre vermell i blanc a dalt. En Bernat preguntà:

—Però per què l’encarregat ha llençat un dels retalls?

—Ja veig que t’hi has fixat. N’Albert anota cada una de les diferències que veu respecte de la versió oficial del Llibre en un retall de paper. A vegades però, hi ha alguna diferència que l’encarregat considera que no és important o que no està segur de si la vol incorporar al registre. És el que ha passat amb la que has vist. L’important és que entre n’Albert i l’encarregat confegeixen (add i  rm) la llista (índex) que s’ha de registrar. La nova pàgina s’encola al Llibre i jo no es mou d’allí. Amb el temps el Llibre (log) s’ha anat engruixint considerablement. La pàgina actual es marca sempre amb un punt de llibre vermell. El senyor Esteve insisteix en que tots els canvis es mantinguin sempre al Llibre i no s’arrenqui mai cap full per antic que sigui. Hi ha altres punts de llibre, mira:

La dona va obrir el Llibre per un punt que tenia escrit “Temporada d’estiu 1880” (tag).

—Aquest sistema permet a la tenda recuperar l’aspecte que tenia en qualsevol moment de la història a base de desfer els canvis anotats fins arribar al full corresponent.

On entren les versions en escena

—Però no entenc perquè cal el punt vermell, el darrer full no és sempre el bo?

—Durant uns anys va ser així. Tot era més senzill llavors. Es va complicar quan el senyor Esteva es va casar. La seva  dona li va començar a dir que era un antiquat, que s’havia de renovar i que més li valdria contractar un artista pintor per fer dissenys trencadors i actuals. Al final l’amo es va convèncer i va llogar un artista de molt renom (tot i que no s’en fiava gaire). Li van deixar una secció del magatzem per a fer les seves proves però era un garbuix: Un dia passaves al vespre i pensaves “mira, doncs està prou bé!” però l’endemà l’artista s’havia llevat amb el peu dolent et deia que tot el que havia fet el dia abans no valia per a res (de fet, feia servir una paraula molt més gruixuda) i ho esbotzava tot per començar de nou. Per a no perdre les bones idees, l’amo em va encarregar de portar un altre Llibre per a aquesta secció i afegir un full nou cada vespre en tancar.

Però va arribar el moment que vam haver d’ampliar la tenda i ens calia aprofitar aquell tros de magatzem. A partir d’aquell moment els experiments els vam fer al mateix lloc que l’aparador oficial. L’artista venia els diumenges i muntava les seves idees. L’endemà els nois ho desmuntaven i muntaven de nou la distribució oficial ajudant-nos dels dos Llibres. Al final portar dos Llibres també va ser un embolic i els senyor Esteve va decidir que només hi hauria un Llibre que contendria tots els fulls.  Nomès que el darrer full de l’artista portaria un punt blau, mentre el full oficial portaria el punt vermell. És per això que el darrer full no és sempre el del punt vermell.

—Però com sabeu què és el que hi ha muntat en cada moment?

—Per a això tenim el punt blanc que assenyala el darrer full muntat. Normalment aquest punt coincideix amb el punt vermell o blau.

La casa creix i s’expandeix

Uns temps de bonança van fer que la casa obris sucursals. Per tal d’assegurar que totes les oficines tenen el mateix aparador, les seus s’enviaven per correu els fulls que calien. Una seu demanava per telègraf  els fulls que li faltaven fins a arribar al punt vermell, per exemple (pull). Ara tenim més artistes contractats i no tots treballen a la case mare, sinó  que treballen a la tenda que els és més avinent. En aquest cas els fulls que es fan remotament s’envien (push) per correu a la seu (amb la indicació de canvi de punt, és clar).

De tant en tant alguna tenda proposa un aparador per a la temporada següent. Ara bé, només l’artista resident pot fer avançar el punt vermell sense consultar a direcció. Pels altres casos, la tenda que fa la proposta envia els fulls amb un nou punt (merge request). Llavors direcció ho munta i ho prova aprofitant un dia de festa. Si s’accepta la proposta, es fa un nou full per a modificar l’oficial per a que coincideixi amb la proposta (merge) i aquest passa a ser el punt vermell.


1 No, no es va fer així

2 Hom pot sentir aquesta “L” inicial quan el senyor Esteve la pronuncia.