Utveckling

Utvecklingen av Koha går snabbt framåt. Inom Koha:s community talar man om utveckling i form av buggar, men termen gäller för såväl buggar som ny funktionalitet. På den här sidan beskrivs hur ny utveckling blir en del av Koha:s kodbas inklusive kvalitetsgranskningsprocessen, lokala anpassningar och samarbetsområden.

Kohas utvecklingsprocess i korta drag

Koha är till sin natur ett distribuerat och demokratiskt projekt och de som bidragit har använt sin upphovsrätt för att garantera dig att du får anpassa din egen installation fritt. Men lokala förändringar blir snabbt ohanterliga vid uppgradering och därför bör du sträva efter att göra alla ändringar "uppströms" dvs få dem inkluderade som en del av en officiell Koha-version. På det viset minskar du problem för dig själv, ger tillbaka till gemenskapen och tvingar andra att förhålla sig till din kod när systemet utvecklas vidare. Den här texten är ett försök att ge en översikt till hur utvecklingsprocessen går till.

• Identifiera ny utveckling du vill göra eller en bugg du vill rätta.

• Försök ta reda på om någon annan redan rapporterat denna eller liknande information på Kohas ärendehanteringssystem Bugzilla[1].

• Om det verkligen är en ny funktion/bug - skapa en ny tråd på Bugzilla (file a bug [2] / välj "Koha") och beskriv så koncist som möjligt vad du vill göra. Fyll i component (vilken del av Koha utvecklingen rör), version (särskilt om det är en bug - "master" avser aktuell utvecklingsversion och funkar för önskad utveckling), summary (supertydligt och de viktigaste orden först - den här raden tenderar att dyka upp i t.ex. release notes) samt description. Severity kan du försöka sätta om du känner att du behärskar de olika stegen medan "hardware" och "OS" kanske används mera sällan men är viktiga i vissa mer avgränsade fall.

• Gör den utveckling som du vill ha gjord - men sätt i så fall dig själv som "Asignee" på bugzillatråden (det finns antagligen en som är default, men det betyder bara att de bevakar vad som kommer in - inte att de skall koda allt som föreslås). Använd t.ex. en Kohadevbox[3] för att enkelt få en virtuell utvecklarmaskin. Läs in dig på Koha developer handbook[4] på den internationella wikin. Posta dina ändringar till Bugzilla (med git bz som du vet mer om efter att ha läst developer handbook). Var noga med att följa reglerna för hur man kodar i Kohaprojektet och att skriva en ordentlig testplan. Om du lämnar bort utvecklingen till en firma kan du fylla i fältet "Change sponsored" så att du/ditt bibliotek syns i release notes för den version där det du finansierar faktiskt kommer med.

• Ändra statusen på bugzillatråden till "Needs signoff" och vänta. När du skickat in din kod måste någon som inte är kopplad till dig granska det du gjort och godkänna det - en så kallad signoff. Den personen ändrar status-fältet på din Bugzilla-tråd och sätter det förhoppningsvis till "signed off". Det är helt ok att nämna att du har en färdig patch för testning men kom ihåg att du inte kan kräva något av någon. Lättast att få signoffs på det du skapar blir det om du också bidragit innan till att testa andras kod. Det kan hända att din kod inte klarar signoff utan måste få ytterligare handpåläggning. I början är det rentav troligt.

• Nästa steg är QA (quality assurance). Det är ett team med frivilliga som har till uppgift att kontrollera att koden inte bara verkar göra det den skall utan bieffekter utan att den också följer den kodstandard som gäller i Koha. Här får du oftast "failed QA" eller "passed QA". Om du inte klarar QA har du ändå kommit långt - justera koden efter teamets instruktioner och ändra statusen på bugzillatråden igen. QA-ansvarig är i skrivande stund Katrin Fischer (cait på IRC) som är mycket hjälpsam.

• Efter att du passerat QA hamnar koden hos release manager för kommande Koha-version. Det är denna person som har sista ordet om ifall din kod kommer med eller inte. I regel får din bugzillatråd statusen "pushed to master" vilket betyder att den nu inkluderas i senaste utvecklarversionen av Kohas kodbas - det som skall bli nästa version. Notera att ny funktionalitet endast släpps vid halvårsversionerna av Koha medan rättningar av buggar och andra mindre justeringar kommer med i månadsversionerna. Det kan också hända att din patch plockas upp av de som ansvarar för äldre versioner av Koha.

Infoga egen HTML, Javascript (jQuery) och CSS

Kohas beteende kan ändras mycket med hjälp av systemparametrarna. Men när det inte räcker finns det goda möjligheter att ändra ytterligare med hjälp av javascript och CSS. Man kan naturligtvis ändra direkt i Kohas programkod, men det skapar problem med uppdateringar. Istället bör du använda de systemparametrar som redan finns förberedda för att infoga HTML, javascriptkod eller CSS i valda delar av systemet. På det sättet stannar ändringarna kvar när du uppdaterar Koha nästa gång. Det finns gott om nischade systemparametrar för att manipulera enskilda delar av gränssnittet, men de som är mest generella torde vara:

• OPACuserJS - Här klistrar man in kod som är som skall finnas tillgänglig på alla sidor i opac. Exempel som andra i nätverket funnit användbara finns på en egen wikisida Kohas OPACUserJS systeminställning

• OpacAdditionalStylesheet - Här länkar du till en extra stilmall utöver Kohas befintliga.

• opaclayoutstylesheet - Sökväg till en ny stilmall för opacen.

• OPACuserCSS - Extra CSS som skall finnas på alla sidor i opac i tillägg till de existerande stilmallarna (om du t.ex. infogat nya HTML-element.

• OpacMainUserBlock - HTML-kod som skall infogas i mittenytan på opacens förstasida.

• OpacNav - HTML-kod som skall visas i vänsterspalten på opacens förstasida.

• OpacNavRight - HTML-kod som skall visas i högerspalten på opacens förstasida.

• OpacNavBottom - HTML-kod för vänsterspalt på opacens förstasida och låntagarens konto (visas under OpacNav)

• opacheader - HTML-kod för sidhuvudet på alla sidor i opac.

• opaccredits - HTML-kod för sidfoten på alla sidor i opac.

(Notera att det finns ytterligare systemparametrar som låter dig infoga html på mer nischade ställen som t.ex. rutan för facetterna, ersätter sökrutan med egen kod, lägger till saker på vidaresökningsknappen osv)

• intranetstylesheet - Länk till en CSS-mall som ersätter den befintliga för Kohas personalgränssnitt.

• intranetUserCSS - CSS-kod som du vill lägga till utöver den befintliga i Koha.

• intranetcolorstylesheet - Länk till CSS-mall som låter dig skriva över delar av den befintliga CSS-mallen för personalgränssnittet.

• intranetmainUserblock - HTML som du vill visa i en egen kolumn på personalklientens förstasida (t.ex. djuplänkar till ofta använda funktioner eller widgets som visualiserar data från systemet). Lämpar sig bäst för mer statiskt innehåll - för t.ex. intern information lämpar sig antagligen det grafiska verktyget för att skriva nyheter bättre.

• intranetNav - Länkar som du vill lägga till under fliken "mer" i personalgränssnittets globala navigation.

• IntranetUserJS - Javascript (jQuery)-kod som du vill ladda på alla sidor i personalklienten. (vad som faktiskt körs kan dock naturligtvis styras med villkor som body-tagens id osv)

Du hittar fler under t.ex. personalklient/utseende och opac/utseende i systeminställningarna.

OBS! När du infogar javascript (troligen vill du använda använda jQuery som redan finns laddat, men vanlig rå javascript funkar naturligtvis också) så skall du låta sidan ladda färdigt genom att skriva din kod inuti följande kodsnutt.

$(document).ready(function(){ <skriv din kod här> });