Guia del professor — Sessió 4 (Fase 4)

«Crear apps amb IA, des de zero»

Treballa com un equip: branques, pull requests i revisió amb IA. Avui els alumnes deixen de tocar main directament i aprenen el flux professional bàsic de GitHub, tot al navegador i sense instal·lar res. Crear una branca, fer el canvi amb l'agent (reutilitzant el mètode del context de la S3), obrir un Pull Request, entendre el diff, demanar a la IA que el revisi abans de fusionar, i fer el merge a main. És una sessió autònoma/online, com la Sessió 2: la fan sols, al seu ritme, amb l'HTML interactiu. Es publica com sempre (copiar a Apps Script); el desplegament automàtic i el treball en equip de debò són la Fase 5 presencial.

1. Fitxa de la sessió

Què s'enduen (resultats d'aprenentatge)

• Entendre per què existeixen les branques: main és la versió bona; cada canvi es fa en una branca a part per no trencar-la.
• Saber crear una branca a partir de main (des del Codespace o des de github.com).
• Fer un canvi a la branca amb l'agent (mètode del context de la S3) i commit + push A LA BRANCA, no a main.
• Obrir un Pull Request (PR) i llegir-ne el diff (què canvia, en verd/vermell).
• Demanar a la IA que revisi el canvi (errors, seguretat, millores), llegir-ne la resposta i decidir — una destresa nova i molt valuosa.
• Fusionar (merge) el PR a main, esborrar la branca i posar al dia la còpia local (canviar a main i fer pull).
• Les bases del treball en equip: cadascú a la seva branca, PRs i revisió; main és de tothom.

El lliurament per a la propera presencial (Fase 5)

Cada alumne ha de venir amb el seu repositori i almenys un Pull Request fet i fusionat (i, si han pogut, la revisió amb IA aplicada). Així a la Fase 5 ja saben el flux i ens podem centrar a col·laborar en equip de debò i a automatitzar la publicació.

Requisits previs (comprova'ls a l'inici)

1. El repositori de la Sessió 3 amb la seva app a dins (Codi.gs, Index.html, carpeta context/).
2. Compte de GitHub propi (creat a la S3) i, idealment, saber obrir el seu Codespace.
3. Compte PERSONAL de Google i la seva app publicada a Apps Script (per recordar que es publica com sempre).

Si algú no té el repo de la S3 (va faltar, no el va acabar), no t'aturis: que en faci un de ràpid o n'agafi un d'exemple (vegeu Pla B, secció 5). L'ideal és treballar sobre la seva app.

2. Com funciona aquesta sessió (autònoma) i el teu paper

Com la Sessió 2, la 4 és autònoma/online: l'alumne la fa sol, amb l'HTML interactiu que el guia pas a pas. El teu paper és enviar, donar suport i preparar el lliurament:

• Abans (enviar): envia'ls l'HTML i deixa clar el termini («tens fins a la propera presencial»). Recorda'ls que necessiten el repo de la S3 amb la seva app.
• Durant (suport asíncron): atén pel xat de classe o correu els encallaments típics (taula de la secció 4). El més probable: fer commit a main per error, no trobar on crear/canviar de branca, i no veure el botó del PR després del push.
• El lliurament: cada alumne ha de venir a la Fase 5 amb almenys un PR fet i fusionat al seu repo (i, si ha pogut, la revisió amb IA aplicada). Aquest és l'objectiu mínim de la sessió.

Prepara't tu primer. Fes el flux sencer una vegada en un repo de prova: branca → canvi amb l'agent → commit/push a la branca → PR → demanar revisió a la IA → merge → esborrar branca → tornar a main i pull. Si el fas en ~20 min, sabràs desencallar qualsevol dubte asíncron. Localitza bé el selector de branca a baix a l'esquerra del Codespace i el botó verd Code / New branch a github.com: són els dos punts on més es perden.

Si algun dia fas aquesta sessió presencial, aquest mateix minutat et serveix de guió: tu fas la demo del flux i ells el repliquen amb la seva app.

3. Minutat orientatiu (~150 min de feina de l'alumne)

Com que la sessió és autònoma, aquest minutat és el temps orientatiu que hi dedicarà l'alumne (al seu ritme, no un rellotge de classe). El cor de tot és obrir el PR, revisar-lo amb IA i fusionar-lo (Blocs D–F): si algú va molt just, que faci com a mínim una branca + un canvi + un PR amb revisió + el merge. El repte «amb un company» és opcional.

Total: 150 minuts.

Bloc A — Per què branques (15 min)

El per què és el cor del dia. Si entenen això, la resta és mecànica. No el corris.

• La idea, en una frase: «main és la versió bona i publicada. Perquè no es trenqui mentre proves coses, cada canvi el fas en una branca a part. Quan funciona, la fusiones a main.»
• Analogia (a l'estil del curs): «main és el document net que ja has entregat. La branca és una fotocòpia per fer-hi proves: hi escarbotes tranquil, i només passes a net el que t'agrada.»
• Connecta amb la S3: «Fins ara treballàveu sempre a main —i estava bé per començar—. Avui aprenem a treballar sense por de trencar res, que és com ho fan els equips de debò.»
• El marc honest d'avui (important dir-lo aviat): «De moment, fusionar un PR a main no publica res sol —seguim copiant a Apps Script—. El valor d'avui és seguretat (no trencar main) + revisar abans de fusionar + preparar el treball en equip. A la Fase 5, el merge a main publicarà sol.»

Frase per repetir: «main és la versió bona. Les proves, sempre en una branca.»

Bloc B — Crear una branca a partir de main (15 min)

Tot al navegador, sense instal·lar res. Hi ha dues vies equivalents; que triïn la que els vagi millor.

• Via Codespace (recomanada si ja el dominen de la S3): al Codespace, el selector de branca és a baix a l'esquerra (mostra main). En clicar-hi, l'editor ofereix crear una branca nova a partir de l'actual. Posa-li un nom descriptiu, p. ex. millora-cercador o arregla-data.
• Via github.com (la més visual i a prova de bombes): al repo, el selector de branques (a dalt, on diu main) → escriure el nom nou → Create branch (Crear branca).
• El missatge clau: «Quan creus la branca, fas una còpia de main per treballar-hi tu. main queda intacta fins que decideixis fusionar.»
• Comprovació d'or: que mirin que el selector ja no diu main, sinó el nom de la seva branca. «Si encara hi diu main, encara no esteu a la branca: torneu a seleccionar-la.»

Noms de branca: lletres, números i guions; sense espais ni accents. Que sigui curt i descrigui el canvi.

Bloc C — Fer el canvi a la branca amb l'agent (25 min)

Aquí reutilitzen tot el que ja saben de la S3: el mètode del context i el flux copiar-enganxar. L'única novetat és on desen: a la branca, no a main.

1. Tria un canvi petit i real per a la seva app: una millora (un camp nou, un filtre, un retoc de disseny) o un arreglo. Millor petit: la gràcia d'avui és el flux, no la mida del canvi.
2. Demana-ho a l'agent com sempre: pots recordar-li el context («segueix la carpeta context/») i demanar-li el canvi concret. L'agent torna els fitxers afectats (sovint Codi.gs i/o Index.html), sencers.
3. Aplica el canvi als fitxers del repo (substituir-los) estant a la branca.
4. Commit + push A LA BRANCA (el punt que més vigilarem): - Al panell de Source Control del Codespace, escriure un missatge de commit curt («Afegeixo el cercador»), fer Commit i després Sync / Push. - Comprova en veu alta (a l'HTML): «Abans de fer commit, mira el nom de la branca: ha de ser la teva, no main.» - Si treballen per github.com: editar el fitxer estant a la branca i fer Commit triant «Commit directly to the nom-branca branch».

Error número 1 del dia: fer el commit a main per error. Recorda'ls abans de cada commit: «mira el nom de la branca a baix a l'esquerra». Si ja ho han fet a main, vegeu la solució a la taula de la secció 4 (no és greu).

Bloc D — Obrir el Pull Request i entendre el diff (20 min)

El Pull Request és «demanar fusionar la meva branca a main». És el moment on el canvi es fa visible i revisable.

1. Després del push, github.com sol mostrar un botó groc/verd «Compare & pull request» (Comparar i obrir pull request). Si no surt sol, anar a la pestanya Pull requests → New pull request i triar: base = main, compare = la teva branca.
2. Posar-li un títol clar («Afegeixo cercador a la llista») i, si volen, una frase de descripció. Create pull request.
3. Entendre el diff (clau): a la pestanya Files changed (Fitxers modificats) es veu què canvia: - Verd (+) = línies afegides. - Vermell (−) = línies tretes. - «El diff és el resum del canvi: d'un cop d'ull veus exactament què tocaràs a main. Sense haver de llegir tot el fitxer.»
4. Missatge clau: «Obrir un PR no fusiona res encara. És una sala d'espera: primer es revisa, després es fusiona.»

Si el botó «Compare & pull request» no apareix, no és un error: és que el push fa estona o estan mirant una altra pàgina. Recarrega el repo o ves a la pestanya Pull requests i obre'l a mà.

Bloc E — Revisar amb IA (25 min) LA DESTRESA NOVA

El moment més valuós de la sessió. Aprendre a demanar a la IA que revisi un canvi i a llegir-ne la resposta per decidir —no per acceptar a cegues— és una destresa que faran servir tota la vida.

1. Què revisem: el canvi concret del PR, no l'app «en general». Per això cal donar-li el material: el diff del PR (o els fitxers nous sencers) enganxat al xat de l'agent / Copilot / Gemini.
2. El prompt de revisió (a l'HTML i a l'Annex B): demanar-li que busqui errors, problemes de seguretat i possibles millores, i que ho expliqui en català i senzill.
3. Llegir la resposta i DECIDIR: - Si assenyala un error o un risc de seguretat real → tornar a la branca, fer el canvi, commit + push; el PR s'actualitza sol (no cal obrir-ne un de nou). - Si proposa una millora opcional → decidir si val la pena ara o més tard. - Si diu que està bé → endavant cap al merge.
4. Missatge clau: «La IA et dona pistes; decideixes tu. Revisar serveix per entendre el canvi, no per acceptar-lo a ulls clucs.»

Error típic: que l'agent revisi «en general» (tota l'app) en lloc del canvi concret. La solució és sempre enganxar-li el diff o els fitxers nous. Sense material concret, la revisió és vaga.

Alguns agents poden revisar el PR «sols» si veuen el repo; altres no. Agnòstic d'eina: si el teu no ho fa bé, enganxa el diff a Gemini en una pestanya. El mètode és copiar i enganxar, com sempre.

Bloc F — Fusionar, esborrar la branca i posar al dia la còpia local (20 min)

El tancament del cicle. Quan el canvi està revisat i decidit, es fusiona a main.

1. Merge: al PR, botó Merge pull request → Confirm merge. «El teu canvi ja és a main: la versió bona ara inclou la teva millora.»
2. Esborrar la branca: apareix el botó Delete branch (Esborrar branca). Que el premin: «La branca ja ha fet la seva feina; esborrar-la manté el repo net. No s'esborra res del codi —ja és a main.»
3. Posar al dia la còpia local (el pas que tothom oblida): - Al Codespace, canviar a main (selector de branca a baix a l'esquerra → main) i fer Pull (Sync). - «Així la teva còpia local es posa al dia amb el merge. Si no ho fas, seguiràs editant la branca vella i et faràs un embolic.»
4. Recordatori de publicació: «Fusionar no publica res sol (encara). Per publicar, copies Codi.gs i Index.html a Apps Script i Implementar → Aplicació web (Versió nova), com sempre.»

Per al pròxim canvi: sempre es comença des de main actualitzada i es crea una branca nova. «Una branca per canvi» (l'hereu de «una app, un full nou»).

Bloc G — (Opcional) Amb un company (20 min)

Només per a qui vagi sobrat i tingui ganes. És un tast del treball en equip; el de debò (repo compartit, main protegida) és la Fase 5.

• La idea: convidar un company com a col·laborador del repo (a github.com: Settings → Collaborators → Add people, amb el seu usuari de GitHub). El company pot crear una branca, obrir un PR, i tu el revises (o a l'inrevés).
• Què practiquen: que la revisió la pot fer una persona (un company) o la IA, i que main és de tothom.
• Missatge: «En equip, cadascú treballa a la seva branca i obre PRs; main és comuna. Avui ho tastem; a la Fase 5 ho farem de debò sobre un repo compartit.»

Si no tenen amb qui aparellar-se, salta aquest bloc: és opcional i no entra al lliurament mínim.

Bloc H — Tancament, checklist i lliurament (10 min)

• Checklist de l'HTML interactiu (per comprovar):
• [ ] Entenc per què es treballa en branques (no trencar main).
• [ ] He creat una branca a partir de main.
• [ ] He fet el canvi a la branca i he fet commit + push A LA BRANCA.
• [ ] He obert un Pull Request i sé llegir el diff.
• [ ] He demanat a la IA que el revisi i he decidit què fer.
• [ ] He fusionat (merge) el PR, he esborrat la branca i he tornat a main + pull.
• Lliurament per a la Fase 5: «Vine amb el teu repo i almenys un PR fet i fusionat (i, si has pogut, la revisió de la IA aplicada).»
• Pont a la Fase 5 (secció 7) en una frase il·lusionant.

4. On s'encallaran SEMPRE i com desencallar-los (suport asíncron)

Truc de prevenció (digues-ho a l'HTML i al xat): abans de cada commit, mirar el nom de la branca a baix a l'esquerra. Aquest sol hàbit evita la meitat dels embolics del dia.

5. Pla B de contingències

Si algú no té el repo de la S3

• Que en creï un de ràpid (repo nou amb la seva app, com a la S3) o que faci servir un repo d'exemple que els hagis preparat. N'hi ha prou per practicar branca → PR → revisió → merge: el canvi pot ser mínim (un retoc de text).

Si l'agent no els revisa bé

• Que enganxin a Gemini en una pestanya el diff (o els fitxers nous) i el prompt de revisió (Annex B). La revisió queda igual de bé; només canvia on parlen amb la IA.

Si es lien amb les branques (o el Codespace va lent)

• Que ho facin tot des de github.com, amb la interfície web, sense Codespace: crear branca (selector de branques → Create branch) → editar el fitxer estant a la branca → commit a la branca → Pull request → merge. Es perd l'agent integrat, però el flux sencer es manté (la revisió, en una pestanya a part).

Si vas curt de temps (l'alumne)

Si va MOLT just: una branca, un canvi petit, un PR amb revisió de la IA i el merge. Lliurament complert.

6. Errors pedagògics a evitar (tu, professor)

• No el converteixis en una classe de Git avançat. Res de resolució de conflictes de merge, res de rebase, res de clasp/desplegament (tot això és la Fase 5). Avui: branca → canvi → PR → revisió → merge → tornar a main. Prou.
• No defensis cap eina d'IA concreta. El flux base segueix sent agnòstic (copiar-enganxar): «sigui quin sigui el teu agent, enganxa-li el diff i demana-li que revisi».
• Insisteix en el PER QUÈ. No trencar main i revisar abans de fusionar. Si entenen el per què, el com és mecànica.
• La revisió amb IA és per ENTENDRE i DECIDIR, no per acceptar a cegues. És el missatge nou més valuós de la sessió.
• Sigues honest amb el marc d'avui: fusionar no publica res sol encara; el valor és seguretat + revisió + preparar l'equip. A la Fase 5, el merge publicarà.
• Recorda que publicar segueix sent copiar a Apps Script. Si no ho dius clar, esperaran que el merge publiqui i es frustraran.

7. Ponts amb la resta del curs

D'on venen — Sessió 3 (GitHub, Codespaces i el context)

• Ja tenen compte i repositori de GitHub, saben moure's pel Codespace (VS Code al navegador) amb el seu agent, i dominen commit / push / pull i el mètode del context (carpeta context/ amb que-ha-de-fer.md i arquitectura.md).
• Fins ara han treballat sempre a main —i estava bé per començar—. Avui fem el salt natural: deixar de tocar main directament i treballar sense por de trencar res, amb branques i pull requests. La manera de demanar canvis a la IA no canvia (mètode del context, copiar-enganxar); el que canvia és on es desa (a la branca) i que abans de fusionar es revisa.

Cap a on van — Fase 5 (presencial: automatitzar i col·laborar de debò)

• El merge a main publicarà sol: amb clasp, l'app es desplegarà automàticament des de GitHub (s'acaba el copiar a Apps Script a mà). El flux d'avui (branca → PR → revisió → merge) agafarà tot el sentit: fusionar voldrà dir publicar.
• Treball en equip de debò: sobre un repositori compartit, amb main protegida (ningú hi pot fer commit directe: tot passa per PR i revisió). El que avui hem tastat (el repte «amb un company») serà el pa de cada dia.
• Deixa'ls amb ganes: «Avui heu après a treballar sense trencar main i a revisar abans de fusionar. A la propera presencial, fusionar publicarà sol i ho farem en equip de debò.»

Annex A — Frases per a la pissarra / recordatori (per al xat de classe)

• «main és la versió bona. Les proves, sempre en una branca.»
• «Una branca per canvi.» (l'hereu de «una app, un full nou»)
• «Abans de cada commit: mira el nom de la branca a baix a l'esquerra.»
• «El PR és demanar fusionar la branca a main. No fusiona res tot sol.»
• «Diff: verd = afegit, vermell = tret. És el resum del canvi.»
• «La IA et dona pistes; decideixes tu. Revisar és per ENTENDRE.»
• «Per revisar bé, enganxa-li el diff o els fitxers nous, no l'app sencera.»
• «Després del merge: esborra la branca, torna a main i fes pull.»
• «Fusionar encara NO publica. Es publica com sempre: copiar a Apps Script.»

Annex B — Prompt de revisió amb IA (per copiar-enganxar)

Que enganxin a sota del prompt el diff del PR (pestanya Files changed) o els fitxers nous sencers. Sense aquest material, la revisió surt vaga.

Ets un revisor de codi amable i clar. Revisa NOMÉS aquest canvi (no tota l'app).
És una app d'Apps Script (Codi.gs = motor, Index.html = cara, un full de Google
com a rebost). Explica-m'ho EN CATALÀ i senzill, sense tecnicismes.

Digue'm:
1. ERRORS: hi ha algun error o cosa que pugui petar? On i per què?
2. SEGURETAT: el canvi exposa dades, secrets o deixa entrar qui no ha d'entrar?
3. MILLORES: alguna cosa fàcil que el faria millor (opcional)?

Acaba amb una recomanació clara: el FUSIONO tal com està, o el RETOCO abans?

--- AQUÍ ENGANXO EL DIFF O ELS FITXERS DEL CANVI ---

Com llegir la resposta: si assenyala un error o risc real, tornar a la branca, arreglar-ho i fer commit + push (el PR s'actualitza sol). Si són millores opcionals, decidir si val la pena ara. Si diu que està bé, cap al merge. Recorda: decideixes tu.

Font editable: sessio_4/guia_professor_sessio4.md · aquesta pàgina web es genera automàticament des del Markdown.