Näin osallistut avoimen lähdekoodin projektiin GitHubissa

Avoimen lähdekoodin projektiin osallistuminen voi tuntua aluksi suurelta askeleelta. Tietovarastossa on vieraita tiedostoja, keskusteluissa teknisiä käsitteitä ja muutosehdotuksissa kokeneiden kehittäjien nimiä. Ensimmäisen osallistumisen ei kuitenkaan tarvitse olla uuden ominaisuuden rakentaminen.

Hyödyllinen panos voi olla puuttuvan asennusvaiheen lisääminen, virheen toistaminen tai epäselvän ohjeen korjaaminen. Kun ratkaiset todellisen ongelman ja kerrot työstäsi ymmärrettävästi, autat sekä projektin käyttäjiä että ylläpitäjiä.

GitHub tarjoaa osallistumiseen yhteisen työnkulun: tutustut projektiin, valitset tehtävän, teet muutoksen omaan työhaaraan ja lähetät sen tarkastettavaksi. Tässä oppaassa esimerkkinä toimii asennusohjeen täydentäminen.

Valitse projekti, jonka käyttötarkoituksen ymmärrät

Luonteva lähtökohta on ohjelma, kirjasto tai työkalu, jota käytät jo itse. Tällöin tunnet ainakin osan käyttäjän tarpeista ja pystyt arvioimaan, milloin ohje tai toiminto aiheuttaa ongelmia.

Tutustu projektin viimeaikaiseen toimintaan ennen työn aloittamista:

• Onko tietovarastoon tehty muutoksia viime aikoina?
• Vastataanko virheilmoituksiin ja kysymyksiin?
• Käsitelläänkö ulkopuolisten muutosehdotuksia?
• Löytyykö osallistujille selkeitä ohjeita?
• Millä kielellä keskustelua käydään?

Harva päivitystahti ei yksin tarkoita, että projekti olisi hylätty. Valmis ja vakaa työkalu voi tarvita vain vähän muutoksia. Ensikertalaiselle aktiivinen keskustelu ja ymmärrettävät ohjeet kuitenkin helpottavat aloittamista.

GitHub suosittelee etsimään osallistumismahdollisuuksia myös itselle tuttujen projektien parista. GitHubin osallistumisideoita.

Osallistua voi myös ilman ohjelmointia

Projektin kehittäminen sisältää paljon muutakin kuin lähdekoodin kirjoittamista. Käyttäjän näkökulmasta puuttuva ohje voi olla yhtä merkittävä este kuin ohjelmavirhe.

Voit auttaa esimerkiksi:

• Korjaamalla vanhentuneen linkin.
• Täydentämällä käyttöesimerkkiä.
• Parantamalla käännöstä.
• Tarkistamalla asennusohjeen toimivuuden.
• Kirjoittamalla täsmällisen virheilmoituksen.
• Vastaamalla kysymykseen, jonka ratkaisun tunnet.

Valitse tehtävä, jonka pystyt myös tarkistamaan. Jos täydennät asennusohjetta, kokeile lisättävä vaihe käytännössä. Pelkkä uskottavalta kuulostava teksti voi johtaa seuraavaa käyttäjää harhaan.

Pienen muutoksen kautta opit projektin työskentelytavan. Samalla näet, millaisia perusteluja ylläpitäjät tarvitsevat ja kuinka tarkastus etenee. GitHubin ohje osallistumisen aloittamiseen.

Lue projektin osallistumisohjeet

Aloita README-tiedostosta ja etsi sen jälkeen osallistumista käsittelevät ohjeet. Niiden nimi on usein CONTRIBUTING.md, mutta ohjeistus voi sijaita myös dokumentaatiossa.

Osallistumisohje voi määritellä esimerkiksi:

• Kehitysympäristön asentamisen.
• Koodin ja tekstin muotoilukäytännöt.
• Vaadittavat tarkistukset.
• Muutosehdotuksen rakenteen.
• Sopivan kanavan kysymyksille.

GitHub voi näyttää linkin osallistumisohjeeseen, kun avaat uuden issuen tai pull requestin. GitHubin osallistumisohjeiden kuvaus.

Tutustu myös mahdolliseen CODE_OF_CONDUCT.md-tiedostoon sekä projektin lisenssiin. Jos havaitset tietoturvaongelman, tarkista erillinen ilmoitusmenettely esimerkiksi SECURITY.md-tiedostosta.

Projektien käytännöt vaihtelevat. Aikaisemmassa projektissa hyväksytty toimintatapa ei välttämättä sovi seuraavaan.

Etsi rajattu tehtävä ja tarkista keskustelu

Avaa projektin Issues-osio ja etsi tehtäviä tunnisteilla good first issue tai help wanted. Ensimmäinen viittaa uusille osallistujille sopivaan tehtävään, toinen avuntarpeeseen.

Lue tehtävän koko keskustelu. Otsikko voi olla vanha, mutta kommenteissa ratkaisutapa on saattanut muuttua tai joku toinen on jo aloittanut työn.

Jos tehtävän tilanne on epäselvä, kerro lyhyesti, mitä aiot tehdä. Esimerkiksi:

Huomasin, että asennusohjeesta puuttuu asetustiedoston luominen. Voin kokeilla käyttöönoton puhtaassa ympäristössä ja täydentää ohjetta havaintojen perusteella.

Suuresta ominaisuudesta kannattaa keskustella ennen toteuttamista. Näin selviää, kuuluuko idea projektin tavoitteisiin. Pienen korjauksen kohdalla noudata projektin omaa osallistumiskäytäntöä. GitHubin osallistumisopas.

Tee projektista oma fork

Jos sinulla ei ole kirjoitusoikeutta alkuperäiseen tietovarastoon, tavallinen osallistumistapa on fork. Se muodostaa GitHub-tilillesi oman tietovaraston alkuperäisen projektin pohjalta.

Avaa alkuperäisen projektin sivu, valitse Fork, tarkista omistaja ja vahvista luominen. Palaa tämän jälkeen oman forkisi sivulle.

Forkin avulla voit lähettää muutokset omaan tietovarastoosi ja ehdottaa niitä myöhemmin alkuperäiseen projektiin. Alkuperäinen sisältö ei muutu pelkästään siksi, että muokkaat omaa kopiotasi. GitHubin fork-ohje.

Huomaa ero forkin ja kloonauksen välillä. Fork sijaitsee GitHubissa, kun taas kloonaus tuo Git-tietovaraston tietokoneellesi paikallista työskentelyä varten.

Kloonaa fork ja luo työhaara

Seuraavat vaiheet edellyttävät asennettua Gitiä ja toimivaa GitHub-tunnistautumista muutosten lähettämistä varten.

Kopioi oman forkisi osoite Code-painikkeen kautta. Esimerkin osoite ja kansio ovat paikkamerkkejä, jotka vaihdetaan todellisen projektin mukaisiksi:

git clone https://github.com/OMA-TUNNUS/PROJEKTI.git
cd PROJEKTI
git switch -c docs/clarify-installation

Ensimmäinen komento kloonaa projektin. Toinen siirtyy sen kansioon ja kolmas muodostaa uuden työhaaran.

Kuvaava haaran nimi helpottaa työn tunnistamista. Tässä docs/clarify-installation kertoo, että muutos koskee asennusohjeen selventämistä.

Kun kloonaat oman forkisi, origin viittaa tavallisesti siihen. Alkuperäistä projektia kutsutaan usein nimellä upstream, mutta erillinen upstream-etäyhteys täytyy tarvittaessa määrittää itse. GitHubin kloonaus- ja etäyhteysohje.

Tee vain tehtävään kuuluva muutos

Oletetaan, että ohjeesta puuttuu asetustiedoston kopiointivaihe. Lisää se oikeaan kohtaan ja selitä, mitkä asetukset käyttäjän täytyy täyttää.

Säilytä ympäröivän tekstin tyyli. Jos projektissa käytetään englanninkielistä dokumentaatiota, kirjoita lisäys samalla kielellä.

Vältä samalla kertaa muiden kappaleiden järjestämistä tai koko tiedoston uudelleenmuotoilua. Tarkastajan pitäisi nähdä helposti, mikä korjaa alkuperäisen puutteen.

Kokeile ohjeen toimivuutta ja tarkista muutokset:

git status
git diff

Varmista, ettei mukaan tullut paikallisia asetuksia, asennuksen tuottamia tiedostoja tai omaan ympäristöösi liittyviä tietoja.

Jos projekti vaatii dokumentaation tarkistuskomennon, suorita se. Koodimuutoksessa noudata vastaavasti projektin testausohjeita.

Tallenna työ ja lähetä se GitHubiin

Valitse muutettu tiedosto committiin. Tässä esimerkissä ohje sijaitsee README-tiedostossa:

git add README.md
git diff --cached
git commit -m "Clarify configuration setup in installation guide"
git push -u origin docs/clarify-installation

Valmistelualueen vertailu näyttää, mitä olet tallentamassa. Commit muodostaa paikallisen historiatallennuksen, ja push lähettää sen omaan forkiisi.

Vaihda tiedostonimi todellisen muutoksen mukaiseksi. Tarkasti nimetyn tiedoston lisääminen auttaa pitämään mukaan tulevan sisällön hallinnassa.

Jos lähetystä ei hyväksytä, tarkista tunnistautuminen ja etäosoite. Oman forkin sijaan alkuperäiseen projektiin osoittava yhteys voi aiheuttaa käyttöoikeusvirheen.

Commitin ja pushin eri tehtävät on kuvattu myös GitHubin sanastossa.

Avaa pull request alkuperäiseen projektiin

Siirry GitHubissa oman forkisi sivulle ja aloita pull request. Tarkista vertailun suunta huolellisesti:

• Kohdetietovarasto on alkuperäinen projekti.
• Kohdehaara on projektin ohjeiden mukainen haara.
• Lähdetietovarasto on oma forkisi.
• Lähdehaara on juuri luomasi työhaara.

Älä oleta kohdehaaran olevan aina main. Osa projekteista ohjaa muutokset erilliseen kehityshaaraan.

Kirjoita otsikko, joka kertoo korjauksen sisällön. Kuvaa sen jälkeen puuttunut vaihe, tekemäsi täydennys ja suorittamasi tarkistus. Linkitä myös asiaan liittyvä issue.

Tarkista tiedostovertailu vielä ennen lähettämistä. Mukana pitäisi näkyä vain tarkoitettu muutos. GitHubin ohje pull requestiin forkista.

Käsittele palaute rakentavasti

Ylläpitäjä voi hyväksyä muutoksen, kommentoida sitä tai pyytää täydennyksiä. Korjauspyyntö on tavallinen osa tarkastusta.

Jos kommentti jää epäselväksi, pyydä täsmennystä kyseisestä kohdasta. Konkreettinen kysymys auttaa enemmän kuin yleinen ilmoitus siitä, ettet ymmärrä palautetta.

Tee korjaukset samaan työhaaraan, muodosta uusi commit ja lähetä muutokset. Avoin pull request päivittyy haaran mukana.

Vastaa keskusteluun kertomalla, miten huomio on käsitelty. Säilytä asiallinen sävy myös silloin, kun olet eri mieltä.

Projektia saatetaan ylläpitää vapaa-ajalla, joten vastaus voi viipyä. Ehdotuksen hyväksyminen ei myöskään ole automaattista: ylläpitäjät arvioivat sen sopivuutta kokonaisuuteen. GitHubin tarkastusohje.

Valmistaudu seuraavaan osallistumiseen

Kun muutos on yhdistetty, valmistuneen työhaaran voi poistaa. Säilytä fork, jos aiot jatkaa projektissa.

Ennen seuraavaa tehtävää päivitä fork alkuperäisen projektin muutoksilla. GitHubissa tähän voidaan käyttää Sync fork -toimintoa, kun päivitys onnistuu ilman ratkaistavia ristiriitoja. GitHubin synkronointiohje.

Päivitä myös paikallinen lähtöhaara ja luo seuraavalle muutokselle uusi haara. Näin edellisen tehtävän työ ei sekoitu uuteen ehdotukseen.

Ensimmäisen osallistumisen jälkeen tunnet jo yhden projektin käytännöt. Seuraava askel voi olla toisen ohjeen parantaminen, pienen virheen tutkiminen tai uuden osallistujan auttaminen samassa kohdassa, jonka itse juuri opit.