Canvis de codi¶
Aquesta pàgina us ajuda a aconseguir que els vostres canvis a l’Ubuntu Touch es fusionin. Descriuem les coses que busquem en el codi, les comissions i els conjunts de canvis. També donem un cop d’ull al que podem esperar en el procés de revisió del codi.
Assumpcions¶
Aquesta pàgina no inclou informació sobre com desenvolupar aplicacions o canvis a Ubuntu Touch. Per aprendre a desenvolupar components d’Ubuntu Touch, consulteu la secció Programari de sistema Per a aprendre a desenvolupar aplicacions, consulteu les seccions Desenvolupament d’aplicacions o Com desinstal·lar aplicacions.
Aquesta pàgina assumeix que sabeu com escriure els vostres canvis, utilitzar Git per publicar-los, empènyer-los a GitHub o Gitlab segons sigui necessari, forjar un repositori i fer una sol·licitud Pull (PR) a GitHub o una sol·licitud de fusió (MR) a GitLab.
Definicions¶
Atès que utilitzem GitHub i GitLab per al nostre allotjament de codi en funció del component, utilitzem alguns termes de forma intercanviable en aquest document.
- conjunt de canvis
Una sol·licitud de GitHub Pull (PR) o una sol·licitud de fusió de GitLab (MR).
- Informació d’errors
Un problema de GitHub o GitLab.
Raonament¶
Molts usuaris utilitzen Ubuntu Touch en molts dispositius diferents. La funcionalitat de trencament en què es basen aquests usuaris pot ser catastròfica. El nostre procés de revisió ens ajuda a evitar la funcionalitat trencada assegurant algunes propietats del conjunt de canvis.
En particular, volem assegurar-nos del canvi:
compleix els seus propis objectius, com afegir una funció o arreglar un error
no causa cap comportament inesperat
fa que sigui fàcil per a algú fer més canvis en el programari en el futur
Les regles d’aquesta pàgina expliquen com heu d’escriure i documentar els canvis a l’Ubuntu Touch. Seguint aquestes normes fa que el procés de revisió sigui més fàcil per a vostè i per a nosaltres.
Aquests no són absoluts; no rebutjarem automàticament el vostre canvi en funció de si seguiu les regles. Si trenques una regla, assegura’t que puguis explicar per què.
Llista de comprovació de canvis de codi¶
Tingues en compte aquesta llista de comprovació mentre escrius el teu codi i mentre et prepares per publicar els teus canvis.
No publiquis el codi comentat¶
Com a desenvolupadors, sovint comentem codi que només hi és per ajudar-nos a verificar supòsits (com els missatges de registre de consola). Assegureu-vos que això mai ho fa en les vostres comissions. Si heu de desobeir aquesta regla, assegureu-vos d’afegir un comentari explicant per què el codi comentat encara existeix a la font. Si teniu la sensació que heu de fer un comentari a // TODO: o // FIXME:, considereu si la presentació d’un informe d’incidència que faci referència al codi trencat o a l’element TODO seria millor.
Escriu proves per als vostres canvis¶
Si un component té un conjunt de proves, utilitzeu-lo. Assegureu-vos que sabeu com executar les proves per al component i entendre la sortida d’aquestes proves. El fitxer README del component hauria de contenir aquesta informació. Si no i no saps com trobar-lo, pregunta’ns. Estem encantats d’ajudar quan algú està tractant d’aprendre sobre un component per primera vegada. No obstant això, estar preparat per obtenir un munt d’enllaços a la documentació per a un sistema de construcció o marc de proves en lloc d’una llista artesanal d’ordres per executar. Pot ser que això sigui tot el que tinguem temps per a oferir. Si encara estàs confós després de comprovar els materials que has rebut, no dubtis a preguntar-ho de nou amb les teves noves preocupacions específiques. Us agrairíem realment que afegiu el vostre nou coneixement al README del component. El millor moment per escriure documentació és després de fer alguna cosa per primera vegada.
Un cop sàpigues com executar el conjunt de proves, podràs afegir les teves proves. Assegureu-vos de provar tants aspectes de la seva nova funcionalitat com vostè sent que són raonables. Seguiu el costat de més proves: poques vegades us demanem que suprimiu proves, però potser us demanarem que n’afegiu més.
Si noteu que un component no té un conjunt de proves, és un moment excel·lent per a presentar un error en aquest component! Li agrairíem la seva ajuda afegint un paquet de proves, però no li ho requerim.
Segueix les guies d’estil existents¶
Si un repositori té una guia d’estil, utilitzeu-lo. Si no hi ha una guia d’estil, intenteu seguir l’estil existent en el fitxer que esteu canviant el més de prop possible.
Publica la llista de comprovació¶
Molt després d’escriure codi, sovint necessitem entendre com i per què introdueix un error. Els missatges de comissió són el nostre primer pas per entendre aquestes preguntes complexes. Aquesta llista de comprovació ajuda als futurs espectadors del vostre codi a entendre per què és com és.
Per a un exemple d’una sèrie de compromeses que segueix molt bé aquestes directrius, vegeu les tres compromeses a la part superior del registre git log que condueix a 840777f a Lomiri. No tots els canvis requereixen una descripció tan detallada com aquests exemples. Seguiu al costat de més detalls; algun dia, sereu qui mira enrere els vostres compromisos i es pregunta per què els heu fet.
Respon preguntes crucials en els missatges de comissió¶
Fem preguntes com, «què?» «per què?» i «com?» per guanyar context d’una situació ràpidament.
Intenteu respondre aquestes preguntes a les metadades o contingut de la vostra publicació. Fer-ho ajuda els revisors i futurs lectors a entendre el context d’un canvi. Per ordre d’importància, respon:
- Què?
Responeu aquesta pregunta amb les primeres línies del missatge d’entrega. «Què fa el teu compromís?» «».Optimize wallpapers for load times and memory use <https://github.com/ubports/unity8/commit/a81421ac1fe5135b9cff710c3cd819aa1804c6e6>».».
- Per què?
Sempre s’indica el raonament darrere d’un canvi: els errors que soluciona, les característiques que construeix fins, i especialment les limitacions que fan que es vegi més complicat del que espera un espectador. Proporcionar enllaços permanents per emetre informes o documentació si donen context.
- Qui?
Git incrusta el vostre nom i adreça de correu electrònic com a emissor dels vostres canvis. Si algú altre us ha ajudat a escriure els vostres canvis, hauríeu d’afegir-los amb una línia
Co-Authored-By: El seu nom <el-seu-email@exemple.com>al missatge de publicació.
És possible proporcionar alguns d’aquest context en els comentaris de codi en lloc dels missatges de publicació. Els comentaris poden ajudar les persones que només estan llegint el codi sense utilitzar eines com git blame. Tingueu en compte que els comentaris poden quedar obsolets ràpidament en comparació amb el codi proper. Un missatge de publicació només està vinculat al codi que heu escrit.
Per acabar, assegureu-vos d’anticipar-vos a qualsevol pregunta que espereu que tingueu sobre el vostre codi en el futur i respondre-hi.
Fes les comissions el més petites possible, però no més petites¶
Alguns canvis requereixen múltiples passos lògics per completar. Si aquest és el cas, dividiu aquests passos en comissions separades. Cada publicació ha de seguir tota la llista de comprovació de comissió. No ha de requerir cap dels compromisos que venen després d’ell per construir o superar proves.
Diguem que esteu implementant una nova manera de cercar números de telèfon a l’aplicació Dialer. El vostre canvi requereix tres passos diferents:
Correcció d’un error en la cerca actual de números de telèfon
Afegeix una API nova per donar suport a la cerca de nombres nous
Afegeix els elements de la interfície d’usuari per utilitzar la cerca nova
Si feu tots aquests canvis en una única comissió i hi ha un problema en el tercer pas, rebutgem tot el conjunt de canvis. Si dividiu els canvis en comissions separades, la correcció d’errors i l’API nova es podrien afegir al programari de línia principal mentre treballeu en el redisseny de la interfície d’usuari.
Torna a basar els canvis durant la revisió, si és possible¶
És comú que un registre de publicació a GitHub vagi d’alguna manera:
Corregeix un error en la cerca de números de telèfon
Afegeix una nova crida de l’API per a una nova cerca de números de telèfon
Afegeix una interfície d’usuari per a la cerca de nous números de telèfon
Corregeix la IU
Correcció d’errors
Revisa els canvis
Corregeix l’API després dels comentaris dels revisors
Si heu de tornar a aquest registre de comissió en el futur, us confondreu en cap moment. Què van dir els revisors, què era el que estava malament amb la interfície d’usuari i la correcció d’errors?
No afegeixis una publicació nova quan rebis una correcció que afecti la primera publicació de la teva sèrie. En lloc d’això, editeu la primera publicació. Si això canvia la informació del missatge de publicació, actualitzeu-la també.
L’edició de les publicacions requereix aprendre noves eines a Git. Editeu una sèrie de publicacions amb git-rebase. Feu un «push» des canvis resultants amb un «force push», o creeu una branca nova i obriu un conjunt de canvis nou.
Per sort, hi ha eines gràfiques que fan que aquest treball sigui més manejable. Per sort, si no enteneu el que estan fent a la línia d’ordres de Git, és possible que us arruïneu i haureu de tornar a començar a partir de la vostra antiga sèrie. Fins i tot els professionals experimentats de Git desembolicen aquest procés de vegades, no es preocupi. Gairebé sempre hi ha un camí de tornada a la seva vella sèrie.
Cada publicació ha de continuar construint, executant i superant proves després dels vostres canvis.
Formateu correctament el missatge de publicació¶
Mantingues la primera línia del teu missatge d’entrega (el resum) a 50 caràcters o menys. Totes les altres línies del missatge de publicació han de tenir 72 caràcters o menys. Està bé si heu de trencar les regles - alguns canvis no es poden resumir en 50 caràcters, i alguns enllaços són més llargs de 72.
Llista de comprovació de la descripció del conjunt de canvis¶
Assegureu-vos que el vostre conjunt de canvis respon a les preguntes següents en la seva descripció.
Si heu seguit les directrius per als missatges de publicació, probablement podeu copiar la informació rellevant dels missatges de publicació a la descripció del vostre conjunt de canvis. GitHub i GitLab ho fan per vosaltres en conjunts de canvis d’una única comissió. Una descripció que diu, «això és complicat d’explicar; si us plau, llegiu els missatges de publicació», també és acceptable. Confiem en tu per aconseguir un equilibri.
Quin problema resol el vostre conjunt de canvis?¶
Enllaça els conjunts de canvis a l’informe d’incidència que resolen, tant si afegiu una característica com si corregiu un problema. Especifiqueu els dispositius on es produeix el problema o si s’aplica a tots els dispositius. Proporcionar suficient informació perquè algú pugui mirar-la i saber com reproduir el problema o provar la característica. Afegiu aquesta informació a l’informe d’assumpte també si no hi és.
Per exemple:
Com vas comprovar que el canvi va tenir èxit?¶
Tots els canvis requereixen proves per assegurar-se que resolen l’informe d’incidència que estan referenciant. Enumera l’entorn en el qual has provat els canvis, incloent-hi el sistema operatiu sota prova, la seva versió i els dispositius en què has provat. Explica el teu procés de proves. Si no esteu segur de com provar una característica relacionada amb els vostres canvis, esmenteu-la.
Per exemple:
He provat aquest canvi de marcador al Nexus 5. Hauria de funcionar en tots els dispositius, ja que no està modificant res específic del dispositiu, però s’apreciarien més proves. Per solucionar un error, vaig haver de tocar una mica de codi a l’àrea de cerca de números de telèfon (53 53). No estic del tot segur de com provar això per a les regressions.
Cal fusionar algun canvi abans o després d’aquest conjunt de canvis?¶
Alguns canvis depenen d’un o més canvis abans que funcionin correctament. Si aquest és el cas, hauríeu de documentar les dependències en les descripcions del conjunt de canvis. Documenta tots els conjunts que s’han de fusionar abans i després l’actual en una sèrie, si cal.
Per exemple, dieu que heu presentat tres sol·licituds de fusió a GitLab, ubports/core/docs!1, ubports/core/code!2, i ubports/core/infrastructure!3. Han de fusionar-se en aquest ordre. En aquest cas, les seves descripcions de MR tindrien alguna cosa semblant a això:
A
ubports/core/docs!1:ubports/core/code!2 i ubports/core/infrastructure!3 depenen d’aquest MR.
A
ubports/core/code!:ubports/docs!1 s’ha de fusionar abans d’aquest MR. ubports/core/infrastructure!3 depèn d’aquest MR.
A
ubports/core/infrastructure!:ubports/docs!1 i ubports/core/infrastructure!3 s’han de fusionar abans d’aquest MR.
Com és la interfície abans i després del canvi?¶
Si els vostres canvis també canvien l’aspecte de la interfície d’usuari, incloeu captures de pantalla per il·lustrar aquests canvis.
Enviament i revisió¶
Ara que heu comprovat el vostre conjunt de canvis, és hora d’enviar-lo per a la revisió! Gràcies per endavant per contribuir a Ubuntu Touch. Això és el que podeu esperar de nosaltres a mesura que revisem els vostres canvis.
Et respectem¶
Heu triat utilitzar el vostre temps per contribuir a l’Ubuntu Touch. Aquesta decisió mai es pren a la lleugera. Un revisor ha de tractar-vos amb respecte i treballar amb vós cap al vostre conjunt de canvis convertint-se en una part d’Ubuntu Touch.
El respecte és un carrer de doble sentit. Ubuntu Touch és un projecte gran; mai hi ha prou mans per fer tot el treball necessari. Pot ser que trigui un temps que el vostre conjunt de canvis vegi qualsevol atenció, i després d’una llarga espera, és possible que torneu a trobar una petició severa de canvis. Llegiu un missatge d’aspecte sever com algú que intenta treballar el més ràpid possible, no com un intent de ser groller per a vostè. T’estenem la mateixa gràcia.
Fem moltes preguntes¶
Els revisors entenen millor el codi que estàs canviant després de fer-te preguntes sobre com funciona. Potser ja saben què fa el teu codi, però encara et preguntaran. Si podeu explicar com funciona el vostre codi, és més probable que hàgiu fet les proves adequades per assegurar-vos que funcioni.
Si no ets capaç d’articular per què alguna cosa funciona, és una bandera vermella. El canvi probablement funciona al voltant d’un error diferent que pot tornar a perseguir-nos en el futur. Corregir l’error real en lloc de fer solucions és un millor ús del temps.
Demanem canvis¶
Una altra persona que mira el seu codi pot veure problemes amb ell que s’ha perdut. Tant si aquests problemes són ineficiències, problemes d’estil o errors nous, és més probable que els vostres revisors els trobin que vosaltres. No et preocupis si reps un llibre de canvis sol·licitats del teu revisor. Ningú és perfecte. Trobar i solucionar aquests problemes potencials condueix a un Ubuntu Touch més ràpid i estable. No és un insult a les teves habilitats com a desenvolupador.
Podem demanar canvis massius¶
De vegades els revisors miren un canvi i s’adonen que hi ha un problema molt més profund en el component. De vegades es comença a desenvolupar una característica amb els supòsits equivocats en ment i acaben amb un maldestre difícil de codi d’espagueti. De qualsevol manera: aquest no és el camí correcte cap a la destinació. Sigui quina sigui la raó, el seu revisor assenyala els possibles problemes amb el seu canvi i suggereix de manera constructiva una nova direcció per a vostè prendre.
Pot dir-nos que estem equivocats¶
És possible que estiguis segur que un error subjacent no és fàcilment solucionable o que el camí que has pres és el millor. És possible que no tingueu prou temps per fer una correcció correctament com s’ha demanat. Si creus que el nostre rebuig al teu conjunt de canvis és incorrecte per qualsevol motiu, fes-nos-ho saber. Els revisors intenten treballar amb tu per arribar a una solució que sigui millor per als nostres usuaris.
Fusió i manteniment¶
Després d’assegurar que el vostre conjunt de canvis compleix tots els nostres requisits, es converteix en una part d’Ubuntu Touch. Gràcies! Ets membre d’un petit grup de persones que contribueixen a una bonica comunitat. No obstant això, aquest no és el final del treball.
De vegades els vostres canvis trenquen una part de la funcionalitat d’Ubuntu Touch malgrat els nostres millors esforços. És possible que se us demani que ajudeu a investigar l’origen del problema i a preparar una solució si això passa. El vostre canvi es podria revertir si trobem que el vostre canvi va ser la causa directa d’un error i no podem contactar amb vosaltres.
Els col·laboradors nous poden notar que recentment heu treballat en un component amb el qual volen treballar. Li agrairíem que els ajudés a ensenyar-los el que ha après durant aquest procés.
Si no hi ha res més, seguiu per la gent que us agraeix el canvi que heu fet. La comunitat d’Ubuntu Touch és increïblement solidària i agraïda. Seria una llàstima per a tu perdre’t la teva part de les bones vibracions.