Element-viestintäpalvelu

Koha-Suomella on käytössä Element.io viestintäpalvelu, missä käydään kehitykseen liittyviä keskusteluja.

1. Tee itsellesi tunnukset palveluun.
2. Pyydä Koha-Suomen henkilökuntaa lisämään sinut huoneisiin.

Git-versionhallinta

Koha-Suomi käyttää Githubia tiketöinnissä ja kehityksessä.

1. Tee itsellesi tunnukset Githubiin.
2. Pyydä Koha-Suomen henkilökuntaa lisäämään sinulle oikeuksia.
3. Lisää omassa koneessa Gitin username ja email omaan Koha-kehityshakemistoon.
   • https://docs.github.com/en/get-started/git-basics/setting-your-username-in-git
   • https://docs.github.com/en/account-and-profile/how-tos/email-preferences/setting-your-commit-email-address
4. Tee itsellesi Personal access token, jolla voit työntää kehitystä Githubiin. (Uusi tokenia säännöllisesti, ei ikuista voimassaoloa)
   • https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-personal-access-token-classic

Kehityshaarojen luominen ja nimeäminen

Koha-Suomen kehityshaarojen luominen ja nimeäminen

HUOM! Ennen uuden kehityshaaran luomista sen tiedot tulee täyttää Tuotannossa olevat branchit-taulukkoon. Taulukosta löytyvät myös jo olemassa olevien kehityshaarojen järjestysnumerot. Uuden kehityshaaran järjestynumerona tulee aina käyttää isointa mahdollista käytettävissä olevaa numeroa.

Koha-Suomen kehityshaarat luodaan lähtökohtaisesti aina ks[version numero]-kehityshaaran pohjalta (esim. ks24, ks25). Jos kyseessä on kuitenkin ominaisuus, joka on jollain tavalla riippuvainen toisen kehityshaaran koodista, kehityshaara on luotava tämän ominaisuuden kehityshaaran pohjalta.

1. Kun teet uusia ominaisuuksia tietovarantoon, luo muutokselle ensin oma kehityshaara seuraavasti:

• Siirry ensin siihen kehityshaaraan, jonka pohjalta uusi kehityshaara tulee luoda

git checkout ks[version numero] TAI git checkout [kehityshaara]

2. Luo uusi kehityshaara seuraavia nimeämiskäytäntöjä noudattaen:

git checkout -b [kehityshaara]

Koha-Suomen kehityshaarat voidaan nimetä kahdella tavalla riippuen siitä, onko kyseessä Koha-Suomen oma ominaisuus vai yhteisöstä tuotu ominaisuus. Jos kyseessä on Koha-Suomi muutos, nimetään kehityshaara seuraavasti:

ksdev/ks-[kehityshaaran järjestysnumero]-[tietovarannon ID]-[tiketin numero]-[lyhyt kuvaus]

Esimerkki:

ksdev/ks-9999-KOHA-1234-this-is-an-example

Yhteisöstä tuotujen ominaisuuksien kehityshaarat nimetään seuraavasti:

ksdev/ks-[kehityshaaran järjestysnumero]-bug-[yhteisön bugzillan tiketin numero]-[lyhyt kuvaus]

Esimerkki:

ksdev/ks-9999-bug-12345-this-is-an-example

3. Tehtyäsi muutokset tarkista että build-release.sh skriptin ajaminen onnistuu ilman virheitä.

• siirry ensin nykyiseen build-kehityshaaraan
• aja build-release.sh

4. Jos build-release.sh:n ajaminen onnistui ilman ongelmia, lisää kehityshaara Koha-tietovarantoo

git push origin [kehityshaara]

Muutostiedostojen otsikointi

Koha-Suomen muutostiedostojen otsikointi

Koha-Suomen ominaisuuksia sisältävät muutostiedostot eli patchit tulee nimetä seuraavasti:

[Tiketin tietovarannon ID]-[tiketin numero]: [Kuvaava otsikko]

Esimerkiksi, Koha-tietovarannossa sijaitsevan tiketin 1234 muutostiedosto nimetään seuraavasti:

KOHA-1234: Tämä on esimerkki

Tietovarannon ID löytyy tietovarannon kuvauksesta sekä sivulta Tietovarannot ja liitännäiset. Jos tietovarannolla ei ole vielä lyhennettä, on sellainen kehitettävä ennen kuin muutos viedään testeille.

Yhteisön muutostiedostojen otsikointi

Yhteisössä muutostiedostot nimetään seuraavasti:

Bug [yhteisön bugzillan tiketin numero]: [Kuvaava otsikko]

Esimerkki:

Bug 12345: This is an example

Yhteisöön ei hyväksytä muutostiedostoja jotka eivät noudata yllä olevaa nimeämistapaa. Virheellisestä otsikoinnista ilmoitetaan qa-tools-työkalussa. Poikkeuksena tästä ovat skeemamuutokset, joita ei ole tarkoitus lisätä sellaisenaan yhteisön main-kehityshaaraan. Ne nimetään seuraavasti:

DO NOT PUSH! Schema changes

Utilityn päivittäminen

1. Kun rupeat tekemään uusia ominaisuuksia utilityyn, luo muutokselle ensin oma kehityshaara development-haarasta

Siirry ensin development-haaraan ja päivitä se:

git checkout development

git pull origin development

Luo uusi kehityshaara

git checkout -b [KEHITYSHAARA]

2. Tee taikasi uuteen kehityshaaraan.
3. Kun taiat on tehty, vie tekemäsi muutokset development-haaraan.

git checkout development

git rebase [KEHITYSHAARA]

HUOM! Varmista ensin, että development-haaraan ei ole tullut muutoksia. Jos on, päivitä development-haara ja tuo samat muutokset myös kehityshaaraasi näin:

git checkout development

git pull origin development

git checkout [KEHITYSHAARA]

git rebase development

Jos tässä kohtaan tulee merge conflict, muokkaa koodiasi sen mukaisesti.

4. Vie päivitetty development-haara GitHubiin:

git push origin development

5. Kun uusi ominaisuus on testattu ja todettu toimivaksi, vie ominaisuus master-haaraan:

Päivitä ensin master-haara

git checkout master

git pull origin master

git rebase development

Kehityshaarojen muutosten muokkaus ja poistaminen

Jos kehityshaarassa olevaa muutosta on tarpeellista muokata tai poistaa se kokonaan, onnistuu se kätevimmin rebase-komennolla.

1. Siirry Koha-tietovarantoon ja vaihda siellä kehityshaaraksi muokattavaan haaraan.

git checkout [kehityshaara]

2. Avaa tig-näkymä komennolla tig.
3. Siirry siihen committiin jota haluat muokata tai poistaa ja kopio commitin sha näytön vasemmasta alareunasta.
4. Poistu tig-näkymästä.
5. Siirry rebase interactive toiminnallisuuteen, joka avautuu käyttämääsi tekstieditoriin.

git rebase -i [kopiotu sha]~

HUOM! Käytä ~-merkkiä, jotta rebase-toiminto näyttää myös commitin jota haluat muokata. Ilman ~-merkkiä, rebase-näkymässä näkyvät vain valitsemaasi committia seuraavat commitit.

6. Riippuen siitä mitä olet tekemässä, valitse jokin seuraavista lähestymistavoista:

Muutoksen lisääminen committiin

Jos haluat lisätä committiin muutoksia, toimi seuraavasti.

1. Vaihda commitin edessä oleva kirjain e:ksi ja tallenna ja poistu editorista (vaihtelee editorin mukaan).
2. Tee haluamasi muutokset ja lisää ne committiin:

git add [muokattu tiedosto]

git commit --amend

git rebase --continue

3. Jos muokkaus vaikuttaa muihin committeihin, korjaa mahdolliset merge conflictit.

Muutoksen muokkaaminen tai poistaminen commitista

Jos haluat poistaa muutoksia commitista muokkauksen yhteydessä, toimi seuraavasti:

1. Vaihda commitin edessä oleva kirjain e:ksi ja tallenna ja poistu editorista (vaihtelee editorin mukaan).
2. Aja seuraava komento, joka palauttaa commitissa olevat muutokset staged-tilaan.

git reset --soft HEAD

3. Tarkista komennolla git status staged-tilaan palautetut tiedostot ja valitse niistä ne joita haluat muokata tai joiden muutoksen haluat poistaa ja palauta tiedostot unstaged-tilaan:

git restore --staged [tiedostot]

4a. Poista muutokset haluamistasi tiedostoista seuraavasti:

git restore [tähän kaikki commitista poistettavat tiedostot]

4b. Muokkaa tiedostoa lisäämällä siihen muutoksesi ja ajamalla:

git add [muokattu tiedosto]

5. Kun olet tehnyt haluamasi muutokset ja poistot, palauta commit (voit nyt muokata myös muutoksen commit messagea):

git commit -c ORIG_HEAD

6. Tallenna ja sulje editori.

Koko commitin poistaminen

Jos haluat poistaa commitin, toimi seuraavasti:

1. Vaihda commitin edessä oleva kirjain d:ksi ja tallenna ja poistu editorista (vaihtelee editorin mukaan).
2. Commitin tulisi nyt olla poistettu.
3. Jos poistaminen vaikuttaa muihin committeihin, korjaa mahdolliset merge conflictit.

Koha-Suomen koodin checklist

Ennen kuin laitat koodia GitHubiin muistathan nämä:

• Selkeä nimeäminen tiedostoille, tauluille, metodeille ja muuttujille.
• Selkeä kommentointi koodille + pidä huoli sisennyksistä, käytä sisennykseen neljää (4) välilyöntiä. Perl-koodin kanssa voi käyttää perltidyn sisennystapaa.
• Tietokantamuutoksille atomicupdate installer/data/mysql/atomicupdate/, nimeä kommitilla ja tiedostopääte .pl. Lisäksi asennusta varten kohastructure.sql ja/tai sysprefs.sql
• Uudet järjestelmäasetukset oikeille paikoilleen koha-tmpl/intranet-tmpl/prog/en/modules/admin/preferences -hakemiston alla oleviin .pref -tiedostoihin
• Uudet CPAN-moduuliriippuvuudet PerlDependencies-tiedostoon.
• Nimeä commitit ja branchit Koha-Suomi nimeämistavan mukaisesti.
• Jos muutos on menossa myös yhteisöön, pyri ottamaan alusta asti huomioon myös yhteisön koodauslinjaukset. Näin vältyt turhalta työltä siinä vaiheessa, kun yrität saada muutosta läpi yhteisössä.

Yhteisön koodin checklist

Yllä olevan Koha-Suomen checklistin lisäksi muista nämä:

• Jos muutat metodeja/funktioita, muista testata että testit toimivat ja muuta niitä tarvittaessa. Jos kirjoitat uuden metodin/funktion, tee sille oma testi.
  • HUOM! Jos muutat esimerkiksi C4::Circulation.pm moduulia, ei välttämättä riitä että teet muutokset testiin Circulation.t. Aja terminaalissa t/db_dependent/Circulation*, jolloin kaikki C4::Circulationiin liittyvät testit tarkistetaan.
  • HUOM! Aja testit mieluummin yhteisön testikantaan, jossa ei ole paljoa dataa. Jo Siilin testikanta on liian iso esimerkiksi Circulation.t testeille.
• Kirjoita mahdollisimman kattava testausohje.
• Lisää patchin kuvauksen loppuu "Sponsored-by: Koha-Suomi Oy"
• Yhteisön qa-test-tools on hyvä apuväline omien patchien testaamiseen ennen yhteisöön vientiä. Asennusohjeet löydät täältä.
• Varmista koodisi oikea muotoilu perl-tidylla.

Muutostiedoston vieminen yhteisön Bugzillaan

1. klikkaa "Add an attachment"
2. liitä muutostiedosto
3. kopioi muutostiedoston otsikko "Description" tekstikenttään
4. klikkaa "patch" checkboxia
5. kopioi muutostiedoston kuvaus "Comment" tekstikenttään

HUOM! Muista merkitä bugin assigneeksi itsesi ja asettaa bugi "Needs Signoff"-tilaan

Tarkemmat yhteisön ohjeet löydät seuraavien linkkien takaa:

• Coding Guidelines
• Terminology
• QA Test Tools
• Git bz configuration
• Submitting A Patch
• Sign off on patches

Koha-Suomen liitännäiset

Koha-Suomen liitännäisten kehityshaarojen luomisessa ja nimeämisessä noudatetaan seuraavia käytäntöjä:

• master/main:
  • kehitystyötä varten tarkoitettu kehityshaara, joka on käytössä vain testeillä ja nexteillä
• versiohaara:
  • tuotannoissa käytössä oleva kehityshaara, joka sisältää vain tuotantokelpoista koodia
  • nimetään aina kunkin käytössä olevan Kohan version mukaan, esim. ks24, ks25.

Liitännäisten kehitystyössä ja muutostiedostojen nimeämisessä noudatetaan mielellään samoja käytäntöjä Koha-tietovarantoihin tehtävässä kehitystyössä:

[Tiketin tietovarannon ID]-[tiketin numero]: [Kuvaava otsikko]

Liitännäisen ID löytyy liitännäisen tietovarannon kuvauksesta sekä sivulta Tietovarannot ja liitännäiset.