GitHub Issues – pidä projektin tehtävät ja virheet järjestyksessä

Projektin tehtävät alkavat helposti hajota eri paikkoihin. Yksi virhe löytyy keskusteluviestistä, seuraava kehitysidea muistikirjasta ja kolmas omasta muistista. Kun työhön palaa myöhemmin, ongelman tarkka kuvaus tai sovittu ratkaisu on jo unohtunut.

GitHub Issues tarjoaa tehtäville yhteisen paikan projektin yhteydessä. Jokaiselle seurattavalle asialle voidaan kirjoittaa kuvaus, käydä keskustelua ja kerätä etenemiseen liittyvät tiedot. Näin havainto säilyy löydettävänä myös alkuperäisen ilmoittajan poissa ollessa.

Toimiva tehtävienhallinta ei edellytä monimutkaista järjestelmää. Alkuun pääsee selkeillä otsikoilla, muutamalla luokittelutunnisteella ja yhteisellä käsityksellä siitä, milloin tehtävä on valmis.

Mikä GitHub Issue on?

Issue tarkoittaa GitHubissa seurattavaa asiaa. Se voi olla ohjelmavirhe, uusi ominaisuus, dokumentaation päivitys tai muu rajattu työtehtävä.

Jokainen issue saa tietovarastossa oman numeron. Esimerkiksi tehtävään numero 42 voidaan viitata saman projektin keskustelussa merkinnällä #42. Viittaus auttaa yhdistämään asiaan liittyvät keskustelut ja muutosehdotukset.

Issuen sisältöä voidaan täydentää työn edetessä. Alkuperäisen kuvauksen jälkeen kommenteissa voi selvittää ongelman syytä, vertailla toteutustapoja ja kirjata päätöksiä.

GitHub Issues soveltuu myös muuhun kuin ohjelmointiin. Sillä voi seurata esimerkiksi verkkosivuston sisältöpäivityksiä tai käyttöohjeiden kirjoittamista. GitHubin Issues-esittely.

Kirjoita otsikko, joka kertoo tehtävän sisällön

Hyvä otsikko auttaa ymmärtämään asian avaamatta koko tehtävää. Tämä korostuu silloin, kun avoimia ilmoituksia on kymmeniä.

Otsikko ”Sivusto rikki” jättää lähes kaiken epäselväksi. ”Yhteydenottolomake ei lähetä viestiä mobiiliselaimessa” rajaa ongelman heti tiettyyn toimintoon ja käyttötilanteeseen.

Kehitystehtävässä otsikko voi kuvata tavoiteltua lopputulosta:

• Lisää hakukenttä artikkeliarkistoon.
• Päivitä asennusohjeen tietokanta-asetukset.
• Näytä tilausvahvistuksessa arvioitu toimitusaika.
• Korjaa alatunnisteen linkkien näppäimistökohdistus.

Vältä yhdistämästä useita erillisiä asioita samaan otsikkoon. Jos tehtävään kuuluu sekä lomakevirhe että etusivun värien vaihtaminen, niiden käsittely kannattaa yleensä erottaa.

Rajattu otsikko helpottaa myös myöhempää hakua.

Kuvaa virhe niin, että toinen voi toistaa sen

Virheilmoituksen tärkein tehtävä on välittää havainto toiselle ihmiselle. Pelkkä toteamus toimimattomuudesta ei kerro, mistä selvittäminen aloitetaan.

Hyvässä ilmoituksessa kerrotaan:

• Mitä olit tekemässä?
• Millä vaiheilla ongelma ilmenee?
• Mitä odotit tapahtuvan?
• Mitä todellisuudessa tapahtui?
• Missä ympäristössä havainto tehtiin?

Esimerkiksi lomakevirheen toistovaiheet voivat olla seuraavat:

1. Avaa yhteydenottosivu puhelimella.
2. Täytä kaikki pakolliset kentät.
3. Paina lähetyspainiketta.
4. Tarkista, ilmestyykö vahvistusviesti.

Kirjaa tämän jälkeen havainto: painike jää lataustilaan eikä käyttäjä saa vahvistusta.

Lisää tarvittaessa selaimen nimi, sovelluksen versio ja virheilmoituksen tarkka teksti. Kuvakaappaus voi selventää tilannetta, mutta poista siitä henkilökohtaiset tiedot ja salaiset tunnisteet ennen julkaisemista.

Määrittele kehitystehtävälle valmistumisen ehdot

Uuden ominaisuuden kuvaus tarvitsee ongelman lisäksi tavoitteen. Ilmaisu ”parannetaan hakua” ei vielä kerro, millainen toteutus voidaan hyväksyä.

Tarkenna, kuka ominaisuutta käyttää ja mitä hänen pitäisi pystyä tekemään. Esimerkiksi artikkeliarkiston haun tarkoitus voisi olla auttaa lukijaa löytämään julkaisu sen otsikon perusteella.

Kirjaa valmistumisen ehdot näkyviin:

• Hakukenttä näkyy arkistosivun alussa.
• Haku löytää otsikossa esiintyvän sanan.
• Tyhjä tulos näyttää ymmärrettävän ilmoituksen.
• Toimintoa voi käyttää näppäimistöllä.
• Haku toimii myös kapealla näytöllä.

Nämä ehdot ohjaavat sekä toteutusta että tarkistamista. Samalla ne ehkäisevät tilanteen, jossa tekijä ja tilaaja tarkoittavat samalla tehtävällä eri asioita.

Pidä ehdot havaittavina. ”Hakukokemus on erinomainen” on vaikeampi todentaa kuin täsmällinen toimintakuvaus.

Käytä tunnisteita johdonmukaisesti

Label eli tunniste luokittelee tehtäviä. GitHubissa tunnisteilla on nimi ja väri, ja niille voidaan lisätä käyttötarkoitusta selventävä kuvaus.

Tavallisia tunnisteita ovat esimerkiksi:

• bug: virheellinen toiminta.
• enhancement: kehitysehdotus tai parannus.
• documentation: dokumentaatioon liittyvä työ.
• good first issue: uudelle osallistujalle sopiva tehtävä.
• help wanted: tehtävä, johon kaivataan apua.

Tunnisteita voi muokata projektin tarpeisiin. GitHubin tunnisteohje.

Aloita pienellä valikoimalla. Jos käytössä on useita lähes samaa tarkoittavia tunnisteita, luokittelu muuttuu epäjohdonmukaiseksi.

Erota tarvittaessa työn luonne ja kiireellisyys. Virhetunniste kertoo ongelmatyypin, mutta ei vielä sitä, pitääkö korjaus tehdä välittömästi. Kiireellisyydelle voi sopia oman selkeästi määritellyn käytännön.

Nimeä vastuuhenkilö ja sovi seuraava askel

Assignee tarkoittaa tehtävään nimettyä henkilöä. Sen avulla muut näkevät, kuka asiaa edistää. GitHubissa tehtäviä voidaan osoittaa itselle tai muille käyttöoikeuksien sallimissa rajoissa. GitHubin Issues-ohje.

Vastuuhenkilön nimeäminen ei kuitenkaan kerro työn vaihetta tai aikataulua. Kirjaa tarvittaessa kommenttiin myös seuraava toimenpide.

Esimerkiksi ”Selvitän ensin, esiintyykö virhe kaikissa mobiiliselaimissa” kertoo enemmän kuin pelkkä käyttäjänimi sivupalkissa.

Jos eteneminen odottaa lisätietoja, täsmennä puuttuva tieto. Pyyntö ”Tarvitsen selaimen version ja virheen toistovaiheet” antaa ilmoittajalle selkeän tehtävän.

Vältä nimeämästä ihmistä vastuuseen ilman yhteistä käsitystä työnjaosta. Näin tehtävälista vastaa todellista tekemistä.

Jaa suuri kokonaisuus pienempiin tehtäviin

Laaja tavoite, kuten verkkokaupan kassauudistus, sisältää helposti monta erillistä työvaihetta. Yksi pitkä keskustelu muuttuu nopeasti vaikeaksi seurata.

GitHubin alitehtävillä eli sub-issueilla kokonaisuuden voi jakaa erikseen käsiteltäviin osiin. Jokaisella alitehtävällä on oma kuvauksensa ja keskustelunsa. GitHubin alitehtäväohje.

Kassauudistuksen osia voisivat olla osoitekenttien muokkaaminen, toimitustapojen esittäminen ja virheilmoitusten tarkentaminen.

Pienen tehtävän sisällä tavallinen tarkistuslista voi riittää. Erillinen alitehtävä on hyödyllinen, kun työ tarvitsee oman vastuuhenkilön, laajemman keskustelun tai itsenäisen tarkistuksen.

Huolehdi siitä, että päätason kuvaus kertoo osien yhteisen tavoitteen. Muuten tehtävien pilkkominen voi peittää sen, mitä kokonaisuudella tavoitellaan.

Kokoa julkaisuun kuuluvat työt välitavoitteeksi

Milestone eli välitavoite kokoaa saman tietovaraston issueita ja pull requesteja yhteisen tavoitteen alle. Sille voidaan määrittää kuvaus ja määräpäivä, ja GitHub näyttää kokonaisuuden etenemistä. GitHubin milestone-ohje.

Välitavoite voisi olla esimerkiksi ”Versio 1.4” tai ”Uuden sivuston käyttöönotto”.

Lisää mukaan vain tehtävät, jotka todella kuuluvat kyseiseen kokonaisuuteen. Kaikkien tulevaisuuden ideoiden kerääminen seuraavaan julkaisuun tekee suunnitelmasta epärealistisen.

Valmistumisprosenttia kannattaa tulkita harkiten. Pienen kirjoitusvirheen korjaaminen ja maksutavan toteuttaminen voivat molemmat olla yksi tehtävä, vaikka niiden työmäärä poikkeaa huomattavasti.

Arvioi siksi myös jäljellä olevien tehtävien sisältöä, älä pelkästään lukumäärää.

Yhdistä korjaus pull requestiin

Issue kertoo, mitä pitää ratkaista. Pull request näyttää ehdotetun toteutuksen. Kun ne linkitetään toisiinsa, ongelman ja korjauksen yhteys säilyy näkyvänä.

Saman tietovaraston tehtävään voi viitata pull requestin kuvauksessa esimerkiksi näin:

Closes #42

GitHubin tukema sulkemisavainsana voi sulkea tehtävän automaattisesti, kun pull request yhdistetään tietovaraston oletushaaraan. Pelkkä viittaus #42 ei tee samaa. GitHubin linkitysohje.

Käytä automaattista sulkemista silloin, kun muutosehdotus ratkaisee tehtävän kokonaan. Jos se toteuttaa vasta ensimmäisen osan, tavallinen linkitys on selkeämpi.

Muista myös erottaa koodin yhdistäminen ja käyttöönotto. Korjaus voi olla päähaarassa ennen kuin se näkyy käyttäjille.

Helpota ilmoittamista valmiilla pohjilla

Issue-pohja ohjaa ilmoittajaa antamaan tarvittavat tiedot. Virheilmoitukselle ja ominaisuusehdotukselle kannattaa tehdä erilaiset pohjat, koska niiden lähtötiedot eroavat toisistaan.

GitHub tukee sekä Markdown-pohjia että lomakkeita. Lomakkeissa voidaan käyttää esimerkiksi tekstikenttiä ja valintoja. GitHubin pohjaohje.

Pidä täyttäminen kohtuullisen kevyenä. Jokaisen kysymyksen pitäisi auttaa käsittelyä.

Virheilmoituksessa ohjelmaversio voi olla välttämätön, mutta kehitysidean ilmoittajalta ei tarvitse pyytää selaimen teknisiä tietoja ilman erityistä syytä.

Kokeile pohjaa itse ennen käyttöönottoa. Jos tavallisen havainnon kirjaaminen tuntuu työläältä, lyhennä lomaketta.

Löydä olennaiset tehtävät haulla ja näkymillä

Tehtävämäärän kasvaessa suodattaminen nopeuttaa työskentelyä. Tietovaraston Issues-haussa voi etsiä esimerkiksi avoimia virheitä:

is:issue is:open label:bug

Itselle osoitetut avoimet tehtävät löytyvät haulla:

is:issue is:open assignee:@me

Hakuehtoja voi yhdistellä tarpeen mukaan. GitHubin hakuohje.

Jos tarvitset taulukon, taulun tai aikajanan, GitHub Projects tarjoaa tehtäville laajempia näkymiä. Sinne voidaan koota työtä myös useasta tietovarastosta. GitHub Projectsin esittely.

Varaa lopuksi säännöllinen hetki tehtävälistan läpikäyntiin. Yhdistä päällekkäiset ilmoitukset viittauksilla, tarkenna epäselvät kuvaukset ja sulje ratkaistut asiat perusteluineen. Ajantasainen lista auttaa valitsemaan seuraavan työn ilman pitkää selvittelyä.