Tämä tiedosto sisältää periaatteita ja ohjeita, joiden mukaan Kipaa olisi hyvä kehittää eteenpäin. Ohjeet ja periaatteet elävät ajassa, niistä pitää keskustella ja niihin voidaan tarvittaessa tehdä muutoksia ja laajennuksia.
Koodissa, kommenteissa, commiteissa ja tiedostonimissä olisi hyvä pyrkiä käyttämään englantia. Englanti on luonteva valinta jo pelkästään Pythonin englantimaisuuden takia. Koodi tosin on monessa kohtaa suomen kielellä, eikä sitä välttämättä erikseen tarvitse lähteä kääntämään. Joitakin termejä voi olla helpompi käsitellä suomeksi.
Pull requesteissa, issueissa, katselmoinneisssa, käyttöliittymässä, dokumentaatiossa ja julkaisutiedotteissa käytetään suomea.
Lyhyt ohje git-versionhallinan käyttämisestä niin, että historiasta tulisi mahdollisimman hyödyllinen.
Ominaisuudet tai muut kokonaisuudet toteutetaan omissa haaroissaan ja sitten haarasta tehdään PR katselmointia varten.
Mahdolliset viitteet tiketöintijärjestelmän tiketteihin tai PR:iin ovat tärkeitä. Kun PR mergetään masteriin on merge-commitin otsikon hyvä olla muotoa #<PR-numero> <Kuvaus kokonaisuudesta>. Merge-committeja ei ole fiksua jättää gitin ehdottamiksi "Merge pull request #42 'user/feature-fix-stuff'", sillä haaran nimi saattaa olla PR:n valmistuessa katselmoitavaksi jo vanhentunut. Commitin tietää merge-commitiksi vaikkei sitä commit-viestin otsikossa lukisikaan.
Käytössä on kolme jatkuvaa haaraa:
master: Julkaisukelpoinen koodi.develop: Kehityksessä käytettävä haara. pull requestien kohde. Mergetään masteriin tehtäessä uutta julkaisua.gh-pages: Kipan verkkosivujen sisältö.
PR mergetään erillisen merge-commitin kanssa. Näin saadaan eroteltua kahden eri tason loogiset muutokset.
Koodin tasolla loogiset yhteen kuuluvat muutokset muodostavat commitin. Kehitettävä ominaisuus taas on kehitettävän järjestelmän tasolla looginen muutos, joka muodostuu commiteista ja ilmenee useimmiten PR:änä. Näitä kahta erottelun tasoa ei pidä seikoittaa keskenään squashaamalla committeja, jolloin tieto committien sisällöstä jäisi yksinomaan GitHubiin.
Ominaisuuden ollessa valmis katselmoitavaksi se rebasetaan kohdehaaraan (useimmiten develop). Tämä tehdään jotta vältytään tekemästä kohdehaarasta kohti ominaisuushaaraa tehtäviä mergejä. Rebasella saadaan myös aikaiseksi "lineaarinen" historia, jota on helpompi ymmärtää ja siitä luodut graafit ovat kauniimpia.
Ominaisuus valmis katselmoitavaksi:
* 19e9c5d (feature) Add integration test
* 0825abc Add feature logic
* 9247ab4 Refactor foo to do bar
/
* 328ac08 Add main.py
* 9659eb1 initial commit
Ominaisuus mergetään git merge --no-ff feature:
* 48b55b6 (HEAD -> develop) #42 Add feature
|\
| * cbde34c (feature) Add integration test
| * 0825abc Add feature logic
| * 9247ab4 Refactor foo to fo bar
|/
* 328ac08 Add main.py
* 9659eb1 initial commit
Tätä merge-strategiaa kutsutaan nimellä "semi linear merge". Azure DevOps:issa voi tämän strategian asettaa käyttöön repositoriotasolla, mutta githubissa ei ole erillistä toimintoa tätä varten.
Mikäli PR muodostuu vain yhdestä commitista, jää merge-commitin tehtäväksi lähinnä viittaaminen githubin PR:ään ja mahdollisiin tiketteihin.