GitHubin haarat ja pull requestit käytännössä

Verkkosivun valikko kaipaa korjausta, mutta samalla projektin nykyisen version pitäisi säilyä muiden käytettävissä. Miten muutosta voi kehittää rauhassa ja näyttää sen toiselle ennen yhdistämistä? GitHubissa tähän käytetään kehityshaaroja ja pull requesteja.

Haara antaa muutokselle oman kehityslinjan. Pull request kokoaa tehdyn työn tarkasteltavaksi ja mahdollistaa keskustelun ennen sen yhdistämistä kohdehaaraan. Yhdessä ne muodostavat työskentelytavan, jota voi hyödyntää ohjelmakoodin lisäksi esimerkiksi dokumentaatiossa.

Tässä oppaassa käydään läpi käytännön esimerkki: verkkosivun mobiilivalikon korjaaminen omassa haarassa ja muutoksen vieminen päähaaraan GitHubin kautta.

Mitä kehityshaara tarkoittaa?

Kehityshaara eli branch on Gitin tapa erottaa rinnakkaiset kehityslinjat toisistaan. Projektin päähaara on usein nimeltään main, mutta käytössä voi olla myös toinen nimi.

Kun luot korjausta varten oman haaran, siihen tekemäsi commitit eivät automaattisesti muuta päähaaraa. Voit kokeilla toteutusta, tallentaa välivaiheita ja pyytää palautetta ennen yhdistämistä.

Samassa projektissa voi olla esimerkiksi seuraavat haarat:

• main: projektin yhteinen päähaara.
• korjaa-mobiilivalikko: valikon toimintaan liittyvä korjaus.
• lisaa-hakutoiminto: uuden haun kehittäminen.
• paivita-asennusohje: dokumentaation täydentäminen.

Pidä yhden haaran työ selkeästi rajattuna. Valikkokorjauksen tarkastaminen vaikeutuu, jos mukana vaihtuvat myös sivuston värit ja asennusohjeet. GitHub flow -ohje.

Mitä tarvitset ennen aloittamista?

Esimerkin seuraaminen edellyttää, että Git on asennettu, projekti on kloonattu tietokoneellesi ja GitHub-tunnistautuminen toimii. Lisäksi tarvitset oikeuden lähettää muutoksia tietovarastoon.

Tässä oletetaan, että:

• Päähaaran nimi on main.
• GitHubiin osoittavan etäyhteyden nimi on origin.
• Valikon toiminta sijaitsee tiedostossa menu.js.
• Työskentelet projektin kansiossa.

Vaihda esimerkkien nimet oman projektisi mukaisiksi. Komentoja ei kannata kopioida ennen kuin tiedät, mihin tietovarastoon ja tiedostoihin ne kohdistuvat.

Jos sinulla ei ole kirjoitusoikeutta alkuperäiseen projektiin, voit yleensä tehdä siitä oman forkin ja ehdottaa muutoksia sen kautta. GitHubin pull request -ohje.

Tarkista lähtötilanne ja luo uusi haara

Aloita tarkistamalla nykyinen haara ja mahdolliset tallentamattomat muutokset:

git status

Jos työtilassa on aikaisempaa keskeneräistä työtä, käsittele se ennen jatkamista. Haaran vaihtaminen ei aina jätä tallentamattomia muutoksia entiseen haaraan, vaan ne voivat seurata mukana.

Kun työtila on puhdas, siirry päähaaraan ja hae sen uusin versio:

git switch main
git pull --ff-only origin main

Valinta --ff-only sallii päivityksen vain suoraviivaisesti ilman yhdistämiscommittia. Jos paikallinen ja etäinen historia ovat eriytyneet, komento pysähtyy tilanteen selvittämistä varten.

Luo tämän jälkeen korjaushaara:

git switch -c korjaa-mobiilivalikko

Komento muodostaa uuden haaran nykyisestä kohdasta ja vaihtaa siihen. Näin korjauksen lähtökohtana on juuri päivitetty päähaara. Gitin switch-ohje.

Tee rajattu muutos ja kokeile toimintaa

Muokkaa seuraavaksi valikon toimintaa editorissa. Tavoitteena voisi olla korjata tilanne, jossa valikko avautuu ensimmäisellä painalluksella mutta ei sulkeudu toisella.

Ennen tallennusta versionhallintaan kokeile ainakin seuraavat asiat:

• Valikko avautuu painikkeesta.
• Toinen painallus sulkee valikon.
• Valikon linkit toimivat.
• Näppäimistöllä käyttäminen onnistuu.
• Muutos ei riko työpöytänäkymää.

Tarkista myös projektin mahdolliset testausohjeet. Selainkokeilu ja automaattiset testit voivat täydentää toisiaan.

Katso lopuksi tekemäsi tiedostomuutokset:

git diff

Vertailusta kannattaa etsiä erityisesti vahingossa poistettuja rivejä, kokeilutekstejä ja muutoksia, jotka eivät kuulu korjaukseen. Pieni kokonaisuus on helpompi ymmärtää myös myöhemmin.

Tallenna korjaus committina

Valitse korjattu tiedosto seuraavaan commitiin:

git add menu.js

Tämä lisää tiedoston senhetkiset muutokset Gitin valmistelualueelle. Jos muokkaat tiedostoa vielä tämän jälkeen, uudet muutokset täytyy lisätä erikseen. Gitin add-ohje.

Tarkista tallennukseen valittu sisältö ja tee commit:

git diff --cached
git commit -m "Korjaa mobiilivalikon sulkeutuminen"

Commit-viestin pitäisi kertoa muutoksen tarkoitus. Pelkkä ”korjauksia” ei auta henkilöä, joka selvittää ongelman syntyä kuukausien päästä.

Yhteen commitiin voi kuulua useita tiedostoja, jos ne muodostavat saman korjauksen. Esimerkiksi valikon ohjelmakoodi ja siihen liittyvä testi sopivat luontevasti yhteen.

Tässä vaiheessa tallennus on paikallisessa Git-historiassa. Se ei vielä näy GitHubissa.

Lähetä kehityshaara GitHubiin

Julkaise haara etätietovarastoon seuraavalla komennolla:

git push -u origin korjaa-mobiilivalikko

Komento lähettää haaran commitit GitHubiin. Valinta -u määrittää paikalliselle haaralle seurattavan etähaaran, mikä helpottaa myöhempiä lähetyksiä.

Kun yhteys on määritetty, saman haaran seuraavat commitit voi tavallisesti lähettää komennolla:

git push

Push ei itsessään yhdistä korjausta päähaaraan. GitHubissa näkyy nyt erillinen haara, jonka sisältöä voidaan vertailla päähaaraan ja käyttää muutosehdotuksen pohjana. Gitin push-ohje.

Jos lähettäminen epäonnistuu käyttöoikeusvirheeseen, tarkista tunnistautuminen ja tietovaraston oikeudet. Virheen syy kannattaa selvittää ennen uusien komentovaihtoehtojen kokeilemista.

Avaa pull request ja tarkista haarojen suunta

Avaa projektin sivu GitHubissa. Uuden haaran lähettämisen jälkeen palvelu voi näyttää Compare & pull request -painikkeen. Voit aloittaa ehdotuksen myös Pull requests -osion kautta.

Tarkista kaksi valintaa:

• Base on haara, johon muutokset halutaan yhdistää.
• Compare on haara, jossa ehdotetut muutokset ovat.

Tässä esimerkissä base on main ja compare on korjaa-mobiilivalikko.

Tutki tiedostovertailu ennen ehdotuksen lähettämistä. Jos mukana näkyy odottamattomia tiedostoja tai runsaasti vieraita muutoksia, selvitä lähtöhaara ja vertailusuunta.

Anna ehdotukselle kuvaava otsikko, kuten ”Korjaa mobiilivalikon sulkeminen toisella painalluksella”. Avaa valmis ehdotus Create pull request -painikkeella. GitHubin luomisohje.

Kirjoita kuvaus, joka auttaa tarkastajaa

Pull requestin kuvauksen kannattaa vastata kolmeen kysymykseen: mikä ongelma oli, mitä muutettiin ja miten tulos tarkistettiin.

Valikkokorjauksen kuvaus voisi olla seuraava:

Mobiilivalikko jäi auki, kun käyttäjä painoi valikkopainiketta uudelleen. Muutos korjaa painikkeen tilan vaihtamisen. Toiminta tarkistettiin kapealla ja leveällä selainikkunalla sekä näppäimistöllä.

Lisää kuvakaappaus tai lyhyt tallenne, jos muutos koskee ulkoasua tai hankalasti selitettävää toimintaa. Kerro myös, jos jokin olennainen tarkistus on vielä tekemättä.

Jos toteutus on keskeneräinen, draft eli luonnos kertoo tilanteesta muille. Luonnosta voi käyttää varhaisen palautteen keräämiseen ennen varsinaista tarkastuspyyntöä. GitHub flow -ohje.

Käsittele palaute samassa haarassa

Tarkastaja voi kommentoida yksittäistä koodiriviä, hyväksyä muutoksen tai pyytää korjauksia. Palaute voi koskea esimerkiksi toimintaa, luettavuutta tai puuttuvaa testiä. GitHubin tarkastusohje.

Tee tarvittavat korjaukset edelleen samassa kehityshaarassa. Tallenna ne uusina committeina ja lähetä GitHubiin:

git add menu.js
git commit -m "Tarkenna valikkopainikkeen tilan päivitystä"
git push

Avoin pull request päivittyy haaran mukana, joten jokaiselle korjauskierrokselle ei tarvitse avata uutta ehdotusta.

Vastaa kommentteihin kertomalla, mitä muutit. Jos ehdotettu ratkaisu ei sovi tilanteeseen, perustele vaihtoehtosi konkreettisesti. Tarkoituksena on löytää toimiva toteutus ja säilyttää päätösten tausta myöhempää käyttöä varten.

Ratkaise mahdolliset yhdistämisristiriidat

Päähaara voi muuttua oman työsi aikana. Jos toinen kehittäjä muokkaa samoja kohtia, Git ei välttämättä osaa yhdistää muutoksia automaattisesti. Tällöin syntyy merge conflict eli yhdistämisristiriita.

Ristiriita voi liittyä esimerkiksi saman rivin erilaisiin muokkauksiin tai tiedostoon, jonka toinen kehittäjä poisti ja toinen muutti. GitHubin ristiriitaohje.

Ratkaisussa pitää selvittää molempien muutosten tarkoitus. Pelkkä oman version valitseminen voi poistaa toisen tekemän tarpeellisen korjauksen.

Noudata projektin käytäntöä haaran päivittämisessä ja käytä editorin vertailunäkymää apuna. Kokeile yhdistetty toiminta uudelleen, sillä ristiriitamerkintöjen poistaminen ei vielä osoita lopputulosta toimivaksi.

Yhdistä hyväksytty työ ja siivoa haara

Kun palaute on käsitelty ja projektin vaatimat tarkistukset ovat kunnossa, pull request voidaan yhdistää.

GitHubissa käytettävissä olevat vaihtoehdot riippuvat tietovaraston asetuksista:

• Merge commit säilyttää haaran commitit ja lisää yhdistämiscommitin.
• Squash and merge kokoaa ehdotuksen muutokset yhdeksi commitiksi.
• Rebase and merge lisää commitit kohdehaaraan uudelleen ilman erillistä yhdistämiscommittia.

Valitse projektin sovittu tapa. GitHubin yhdistämisohje.

Yhdistämisen jälkeen päivitä paikallinen päähaara:

git switch main
git pull --ff-only origin main

Valmiin etähaaran voi poistaa GitHubin Delete branch -toiminnolla. Pull requestin keskustelu säilyy luettavana.

Huomaa vielä, että päähaaraan yhdistäminen julkaisee sivuston vain, jos projektiin on määritetty sitä varten automaatio. Muussa tapauksessa käyttöönotto on erillinen vaihe.