Automatisering av Github 1DV411 Webbteknik 1 - Slutrapport Författare: Hampus Jarleborn Henric Gustafsson Martin Arvidsson Michael Ingvarsson Niklas Johanneson Sandra Hansson Sing Trinh Sverker Söderlund Kund John Häggerud
Sammanfattning Vi har under nio veckor arbetat mot vår kund John Häggerud med att hjälpa honom att förverkliga visionen om att förbättra GitHub hanteringen vid diverse kursstarter genom att automatisera processen av skapning av repositorier och teams. Tanken som han hade var att automatisera så mycket av det som i dagsläget var manuellt arbete. I detta ingick att skapa repositorier med hjälp av kursmallar, som hämtas/sparas undan i ett databas. Presentation av händelser kring de olika repositorier (releases, issues med mera). I denna rapport går vi igenom hur vi strukturerade vårt arbetssätt, projekt mål samt vilka tekniker som användes och hur slutprodukten blev. 2
Innehållsförteckning 1.Inledning 1.1 Bakgrund 1.2 Syfte 1.3 Mål 2. Projektorganisation 3.Genomförande 3.1 Metodik 3.2 Baskrav 3.2.1 Övriga krav, egenskaper & Features 3.3 Teknik 3.3.1 Språk och exekveringsmiljö 3.3.2 En överblick av applikationen 3.3.3 User API 3.3.4 Course Template API 3.3.5 Github API 3.3.6 Interface 4 Resultatbeskrivning 5.Avvikelser 6. Slutsats 7.Vidareutveckling 8. Övertagande organisation 9.Litteraturförslag/dokumentationshänvisning 10.Förslag till förbättringar inför kommande projekt 11. Bilagor 3
1.Inledning 1.1 Bakgrund I sitt arbete som Universitetsadjunkt på Linnéuniversitetet, har kunden John Häggerud upplevt att en väsentlig del av sin arbetstid används till manuell hantering av repositorier på GitHub vid kursstart. Tidigare har alla studenter som registrerats hämtats från Ladok På Webb då en ny kurs startat eller en ny student registrerats, vilket har varit problematisk när elever gör en sen anmälan. För en mer tidseffektiv hantering av tilldelning av repositorier till elever, önskade därför kunden att denna process skulle bli automatiserad Projekt-namnet vi valde för uppdraget var Automatisering av Github repositorier. 1.2 Syfte Syftet med uppgiften som vi fick av kunden var att utveckla en web applikation som hanterar anrop från Coursepress med användarnamn och organisations namn, som behövs för att skapa repositorier till kursens deltagare. Den angivna data ska användas för att hämta elevernas användarinformation (GitHub namn, för- & efternamn) ifrån ett externt API baserad på skolanvändarnamnet. Med organisations namnet hämtas mall som ska användas, också ifrån ett externt API. Data slås ihop och skickas vidare till GitHub för att skapa repositorierna till angivna organisations namn. Det skulle vara möjligt att skapa nya mallar samt möjligheten att ladda upp färdiga mallar. I övrigt ska händelser på dom olika repositorierna övervakas med hjälp av webhooks och presenteras på en separat webbsida. 1.3 Mål Målet med projektet var att processen ska vara automatiserad för att underlätta kundens hantering av Github repositorier. Målet var även att skapa användarvänliga interface för att överse webhooks av olika karaktär samt skapande av nya mallar för en kurs. Applikationen skall kunna knytas samman med interna system, såsom Ladok För Webb i produktion. 4
2. Projektorganisation Uppdragsgivare för projektet är John Häggerud, Universitetsadjunkt, institutionen för datavetenskap på Linnéuniversitet. I egenskap av uppdragsgivare innefattas även kund, samt huvudsaklig intressent. En annan aktör som kan ses som intressent är Linnéuniversitetet. Gruppen valde att tilldela Martin Arvidsson rollen som projektledare, en roll som tidigare Hampus Jarleborn hade. Detta ändrades på grund av att dem båda kände att det vore mer passande att byta roller. Som ansvarig för testning utsågs Sverker Söderlund. Sandra Hansson och Hampus Jarleborn utsågs som kundansvariga, dock har mängden medlemmar på kundmötena varierat. De gånger någon av de kundansvarig haft förhinder deltog Martin som ersättare, vissa demonstrationer har krävt att någon mer deltagit. Teknisktansvariga var Niklas Johannesson samt Michael Ingvarsson, samt i viss utsträckning även Sing Trinh. Github ansvarig, det vill säga den som är ansvarig för commit-standard och dess användning utsågs Henric Gustafsson. 5
3.Genomförande 3.1 Metodik Under projektets gång har vi arbetat iterativt enligt kursens angivna tidsplan. För att producera nödvändiga artefakter, samt för att få ständig återkoppling med kunden. Varje måndag skrev vi veckans iterationsplan och under handledningsmötet brukade vi gå igenom den med vår handledare för att kontrollera att vi låg i fas. Måndagar var veckans första mötesdag där vi gick igenom vilka medlemmar som skulle göra vilka uppgifter, samt hur alla låg till med tidsrapporter osv. Vi jobbade i största del parvis då detta underlättade implementation samt resulterade i starkare kod. Under våra handledningsmöten gick vi även igenom eventuella problem som uppstått och rådgivning över hur dessa skulle lösas. Projektet har genomgått i fyra faser, där den första fasen var Inception. Där utformades dokumentationen vision, projektplan, kravlista, risklista samt tidsplaner för samtliga medlemmar. Här gick vi även igenom hur vi skulle arbeta som grupp när vi nu var så många som vi var samt försökte få grepp om projektets tekniska storlek. I andra fasen elaboration låg fokus på att röja undan de stora tekniska riskerna för projektet, men vi arbetade även med att strukturera upp arkitekturen så alla var med på hur applikationen skulle vara uppbyggd. Under tredje fasen, construction, fortsatte kod implementation och vi arbetade vidare med att röja undan kvarliggande mindre risker. Testningen började ta form under denna fas, vilket egentligen är lite sent men vi lyckades lösa det till slut. Det var även i construction fasen som vi började koppla ihop alla olika delar och såg till att allt fungerar tillsammans. Den sista fasen var Transition, här finslipade vi applikationen och såg till så att det fungerade till redovisningen. Vi utförde även några sista tester och mycket fokus låg även på att få dokumentationen att bli bra. 6
För att hantera dokumentationen har vi använt oss av Google Drive. Inledningsvis hade vi ett dokument för varje tidrapport samt iterationsplan, men vi valde i ett senare skede under projektets gång att sammanställa samtligas tidsrapporter i ett dokument, med flikar för respektive grupp medlem, samt ett dokument för iterationsplanerna, utformad på liknande vis för respektive iteration. Vi bestämde oss även för att istället för att använda google drive för våran product backlog, att använda oss av Waffle I.O. Detta verktyg underlättade arbetet, då det var lätt att få en översikt över vad som behövdes utföras, vem som tagit vilken uppgift och i vilket skede uppgiften var. Vi valde att istället Product Backlog som en historik på samtliga tasks vi utfört eftersom vi bara hade ett visst antal task på Waffle i taget vi kunde arbeta med. Som kommunikationsverktyg valde vi att använda Facebook Messenger då detta var något som hela gruppen hade och kollade dagligen. För kundkontakt valde vi att använda en Slack kanal då detta var det mest effektiva sätt att nå kunden på. Chatten användes som ett internt kommunikations verktyg för att uppdatera övriga medlemmar om förändringar, ställa frågor med mera. Slack användes för att kommunicera med kunden. För att säkerställa att samtliga inom gruppen arbetade på ett konsekvent sätt, utformades en standard för kod samt en för commits till versionshaterings-verktyget Github. Dessa dokument skapades för att ge en standard för hur kod skall utformas, vad commits skulle innehålla, vilka som utfört det samt status på vad som utförts. Denna standardisering har noga följts under projektets gång och har resulterat i en konsekvent och bra strukturerad kod. 7
3.2 Baskrav BK 1. Applikationen skall kunna ta emot data från Coursepress BK 2. Applikationen skall kunna få ut användarnamn från Coursepress (API) BK 3. Extern API med möjlighet att skapa och hämta mall, används av Applikationen BK 4. Applikationen skall kunna skapa repositorier på GitHub enligt mall BK 5. Applikationen skall besitta en databashantering för mallar BK 5. Applikationen skall besitta en databashantering av data från webhooks BK 6. Applikationen skall kunna implementera webhooks till varje repositorie 3.2.1 Övriga krav, egenskaper & Features 1. Källkod skall hålla en hög kodkvalitet, vara välindenterad, ej upprepande och väl kommenterad 2. Dokumentation för Mall API:et 3. Dokumentation för installation av applikation 4. Kunna skapa och/eller ta bort mallar för repositorier 8
3.3 Teknik 3.3.1 Språk och exekveringsmiljö Den ledande tekniken som har använts i projektet är Node JS 4.2.6. Node JS är ett modul-baserat platformsoberoende exekveringsmiljö för serversidan, som drivs på google Chromes V8 motor. Dess moduler är skrivna i Javascript men bör inte anses som ett ramverk, och då det har en event-baserad arkitektur, lämpar sig mycket väl för asynkron input/output. Vi har även använt Express.js - ett ramverk för Node JS vars primära funktion är att förenkla routing. Det möjliggör även enkel databasintegration. Databashantering sker med hjälp av MongoDB, NoSQL (Not only Structured Query Language ) databas, som inte är en relationsdatabas utan är dokumentbaserad. För att underlätta databashanteringen ytterligare används cloud-tjänsten MLab.com som tidigare hette MongoLab. 9
3.3.2 En överblick av applikationen Systemet är indelat i fyra primära delar, var i den centrala delen i illustrationen helt enkelt kallas för Application. Applikationen tar emot ett POST anrop ifrån till exempel Coursepress vilket indikerar att nya repositorier skall skapas. Ett korrekt JSON-format med egenskaperna usernames samt organization ska följas med anropet vilket behövs för att skapa repositorierna. User API:et anropas, som förnärvarande tillhandahålls av ett mockup API som tillhandahåller användarnas användarinformation som GitHub namn. När systemet har tillhandahållit användardatan, anropas ett annat API som vi valt att kalla för Coursetemplate API. Denna API tillhandahåller mallar i en databas där vi utifrån det organisations namn som skickats in som parameter hämtar. Denna mall används sedan som ett mall på hur en repo ska se ut, vi infogar användarinformation från tidigare i denna mall. Sedan när denna process är klar görs en POST anrop mot GitHubs API, som skapar repositorier, webhooks som pekar mot livesidan där webhook datan ska presenteras, som i sin tur sparas i databasen i vårt system. 3.3.3 User API För att simulera den hämtning av data som behövs för samtliga användare, har vi skapat ett mockup API, som vid ett GET anrop tillhandahåller en JSON representation av de efterfrågade användarnas github användarnamn. Vårat mockup API är begränsat till fem testanvändare, men det riktiga API:et har dokumentation över alla användare. 10
3.3.4 Course Template API API:et för hanteringen av mallar fungerar som en mellanhand mellan applikationens centrala del och databasfunktionaliteten. Vid ett GET anrop på /templates/:orgname, tillhandahålls den efterfrågade resursen ur databasen. Template delen tillhandahåller även funktionalitet för att spara nya mallar, utöver att söka efter befintliga mallar. 3.3.5 Github API Vi har kört på den senaste versionen vilket är V. 3. API tillgång sker över HTTPS och datatypen som skickas och tas emot är JSON. För att kunna använda vissa delar av API:et behöver man autentisera sig mot GitHub som användare. Vi gjorde anropen mot https://api.github.com och la till de parametrarna som behöves för det specifika anropen. Som helhet var det ett väldigt bekvämt API att jobba mot då det var väldigt bra dokumenterat. 3.3.6 Interface Mallar På klientsidan har vi använt oss av Javascript samt CSS ramverket materialize. Kodstandarden är baserad på Airbnb, en stilguide för Javascript som finns tillgänglig på Github. Systemet innefattar två interface. Det första tillhandahåller funktionalitet för att söka efter mallar, samt att skapa mallar. För att skapa mallar kan användaren använda det grafiska interface som tillhandahålls, och kan därigenom ange den data som krävs, eller välja att ladda upp en JSON-fil som uppfyller den standard som krävs beträffande data som krävs, samt benämning samt korrekt struktur av objekten Eftersom vår kund är en exceptionellt teknisk kund var detta en funktion som kändes relevant samt som efterfrågats. 3.3.7 Webhook presentation Webhook presenteringen sker genom att vi använder socket.io för att kunna göra snabba uppdateringar på sidan utan att behöva ladda om. När ett repositorie med en webhook som pekar på livesidan gör en POST via att ett webhook event triggas, skickas data till våran applikation där vi hämtar ut dom parametrar som kunden tyckte var viktiga. Webhooken sparas även i databasen så att en omladdning av sidan inte gör att all data på sidan försvinner. Styling på sidan har skett med hjälp utav CSS ramverket materialize. 11
4 Resultat beskrivning Applikationen/systemet möjliggör för kunden att skapa nya repositorier för samtliga elever i en kurs genom ett POST anrop till systemets URL (med data som behövs). Vi har vår själva applikation som tar hand om automatiseringen, vi har mall API:et vilket fungerar som ett separat applikation. Sedan en applikation som tar hand om presentationen av webhooks. Här har vi ett par skärmdumpar på applikationen där vi även förklarar en bit. 4.1 Skapa Mall genom Filuppladdning (figur 4.1) Vill kunden skapa en ny mall, kan han välja att ladda upp en JSON representation av kursen med korrekt data samt struktur. Detta görs genom att klicka på knappen Upload Template samt välja den fil som skall laddas upp. Ifall formatet är felaktigt, kommer systemet svara med ett felmeddelande: Filetype is not ok, only txt or json extension allowed. 12
4.2 Skapa Mall genom Formulär (figur 4.2) Användaren kan även använda det grafiska interface som finns tillgängligt för skapande av mallar. Detta görs genom att klicka på Create Template, samt välja antalet mallar som skall skapas. Maximalt kan 10 stycken mallar skapas. När antalet mallar har valts, måste organisationsnamn, samt beskrivning av kursmallen anges. Namnformat efterfrågas av Githubs API, men fylls automatiskt i av systemet som detsamma som organisationsnamn. Ifall någon av fälten inte fylls i, blir de rödmarkerade, samt ett felmeddelande visas upp som anvisar användaren att fylla i de fält som markerats. Användaren kan även skapa en ny Milestone för repositorierna, genom att klicka på knappen New Milestone. Användaren måste då, utöver ovan nämda fält, fylla i namn samt datum för milestones. 13
4.3 Ett sätt att hitta Mall, som presenteras med indentering (figur 4.3) Användaren har även möjlighet att söka efter en mall, genom att klicka i sökrutan och ange organisationsnamnet för kursen. Hittas en mall, skrivs den ut i JSON format, annars så svarar API:et med statuskod 404 samt felmeddelandet "Template could not be found." 14
4.4 Presentation av Webhooks (Releases, Issues, Comments) (figur 4.4) Användaren har även möjlighet att få en översikt av samtliga issues, issuekommentarer samt releases. Användaren kan använda sökfältet i det högra hörnet för att söka på namn eller organisation eller båda två. Har användaren inte läst en issue, anses den som oläst och har därför en blå rand längs med den högra kanten i listan. Issues färg-markeras även beroende på ifall de är öppnade eller stängda, samt ifall en issue är markerad. En öppnad issue listas som grön och en stängd som röd. Då en issue markeras blir den mörkgrå och tillhörande kommentarer till den markerade issue:n visas i fältet issue comments till höger.efter att ett issue inte längre är markerat blir färgen istället lätt grå. I listan över issues tillhandahålls användarnamn, organisationsnamn, status samt även en länk till github, där issuen visas. I den vänstra spalten visas releases med användarnamn, organisationsnamn, releasenamn, samt länkar till releasen samt nedladdning av källkoden som zip fil. 15
5.Avvikelser Då vi uppfyller samtliga krav som kunden uttryckt skall finnas så erhåller inte detta projekt några större avvikelser. De enda avvikelser som har sett under projektets gång är isåfall att vissa krav av kunden har tagits bort. Detta resulterades i att dessa naturligtvis inte implementerades. Krav som tagits bort har i backloggen markerats som avbruten. 6. Slutsats Sammantaget har arbetet i projektet gått bra, dock inte utan vissa svårigheter samt utmaningar, vilket vi ämnar att redovisa för i detta avsnitt. Det fanns en del svagheter i projektets fundamentala struktur, vilket en del svårigheter till stor del berott på tillhandahåller dock fler lärdomar att ta med oss till nästa gång. En av de saker vi var bra på att hålla en strikt kod och commit standard då dessa sammanställdes tidigt i projektets gång, vilket möjliggjorde ett mer sammanhållet samt strukturerat arbetsätt. Kommunikationen mellan projektgruppen och kunden har även varit god, vilket i stor del kan bero på att vi hade bekvämligheten att få en lärare som kund. Detta innebar naturligtvis en exceptionellt tekniskt kunnig kund, som dock i största mån försökt uppträda såsom en kund vore i vanliga fall. Det innebar även att vi alltid hade möjligheten att gå upp och fråga kunden om något allvarligt uppstod. I övrigt hölls kommunikationen mestadels via Slack eller på kundmötet vilket var tillräckligt för vår del. Då vi fått godkännande från kunden vid slutleverans, upplever vi att kundens krav är uppfyllda och mostvarar de krav som var givna. Vi har fått kontinuerlig respons från kunden, för att säkerställa att vi var på rätt väg, samt uppfyllde de krav som kunden ställt. Kundens krav har dock upplevts något otydliga ibland. Vi upplevde att det var upp till oss att själva utforma de grafiska delarna, exempelvis, så som vi själva ansåg att de skulle se ut med den funktionalitet som vi ansåg relevant. Det vi kunnat göra för att öka klarheten i vad som kunden förväntade sig vore att vara mer tydliga i våra frågställningar mot kunden. 16
På grund av kundens tekniska expertis, hade han redan en klar bild över den övergripande strukturen samt de tekniska lösningar som kunde användas för att lösa de problem som presenterats. Vi upplevde därför inga större svårigheter att presentera lösningar som var i enlighet med kundens vision i det stora hela. Det fanns säkerligen vissa mindre delar som kunde gjorts annorlunda, men i stora drag anser vi att de lösningar som presenteras är enliga med kundens krav. Riktlinjerna för kursen har varit tydliga i stort, med en tydlig arbetsmetod samt specifikationer för de artefakter som bör produceras. En av de delar som har varit bristfällig under projektets gång har varit kommunikationen. Detta ledde till att uppgifter ibland kvarstod trots att de var färdiga eller att de inte gjordes klart till fullo. Dessa kommunikativa svårigheter har även resulterat i en försämrad gruppdynamik och har yttrat sig bland annat genom förseningar till möten. Beträffande gruppmötena skulle vi kanske även ha behövt fler mötestillfällen för att sammastråla som en enhet då vi arbetade till stor del på olika platser. En möjlig lösning till denna problematik vore en gemensam arbetsplats, samt en väl etablerad möteskultur inom gruppen, för att underlätta den kommunikativa delen och därmed skapa mindre påfrestningar på gruppens samanhållning. När det gäller hur gruppen uppskattade tiden till våra tidplaner som vi planerade upp varje vecka, överskattades hur lång tid varje uppgift skulle ta ganska rejält. Vi var väldigt inställda på att få ihop 20 timmar per gruppmedlem vilket ledde till att uppgifternas tidsåtgång överskattades rejält. Under arbetets gång förbättrades tidsuppskattningarna en hel del, dock fortsatte dom att avvika ganska rejält. En av andledningarna till detta kan ha varit att tidsloggandet för alla gruppmedlemmar varierade ganska rejält. 17
Ett annat problem som uppstått är tidsförbrukningen i förhållande till antalet medlemmar, vilket vi uppfattat som ett stressmoment tidvis. Brister i tidsförbrukningen kan även ha anknytning till tidigare nämda problematik, nämligen kommunikationen då avslutade uppgifter inte alltid meddelades - vilket resulterade i att få tog på an nya uppgifter. Även dokumentationen fick en skakig start, då det inte fanns någon etablerad grund för dokumentation och därmed inte några mallar på hur dessa skulle utformas. Efter att ha diskuterat internt i gruppen samt med andra grupper så lyckades vi utveckla fram en stabil och tydlig dokumentation. Dock känner vi att vi inte kunnat göra så väldigt mycket annorlunda, mer än att ha diskuterat dessa frågor i ett ännu tidigare skede av projektet. Vi kunde inte heller leverera en fungerande version av samtliga delar förrän constructionfasen, på grund av projektets struktur. Vi arbetade nämligen parvis med olika delar av applikationen, vars delar bestod av två stycken API. Dessa kunde vi visa upp i olika stadier, för att demonstrera olika funktionaliteter. Det var inte förrän i just Construction fasens första vecka som vi sammanfogade de olika komponenterna. De grafiska interface som kunden ville ha för att få en översikt över webhooks, samt för att kunna söka efter och skapa mallar färdigställdes även i constructionfasen. I efterhand anser vi att vi kunde ha börjat på dessa delar tidigare. Mycket av denna funktionalitet hade låg prioritet, och på grund av andra åtagande eller andra faktorer, såsom kommunikativa svårigheter, blev dessa inte färdigställda förrän sent i projektets gång. Detta vore något som vi kunnat visa upp för kunden tidigare. Vi fick dock nöja oss med ganska länge med tekniska demonstrationer av mindre delar av applikationen, såsom mockup-api:et för att hämta ut användarinformation. Testningen har skett i olika omfattning, beroende på vilken del av applikationen som avses. Dock har vi följt den mall för testfall och testrapporter som tidigt etablerats samt sett till att samtliga delar av applikationen har blivit testad. Vi är därför ganska säkra på att det system som leverats fungerar. Kortsiktigt bör därför systemet som levererats kunna omedelbart knytas an med Ladok samt sättas i produktion för att underlätta kundens arbete. På något längre sikt kanske kunden kommer på fler funktioner som behöver implementeras. Vidareutveckling bör dock inte vara något problem, då en stor del av applikationen består av olika API:er, som inte är hårt knutna till applikationens huvuddel. 18
7.Vidareutveckling och övertagande Vidareutveckling samt övertagande av applikationen kommer att ske av utav våran kund samt andra lärare på fakulteten för teknik. När dom ser behov att lägga till ny funktionalitet eller refakturera existerande funktionalitet har dom full tillgång till teknisk dokumentation som förklarar hur applikationen är uppbyggd och fungerar, detta ska förhoppningsvis göra att vidareutveckling av applikationen kan ske utan några problem. 8.Förslag till förbättringar inför kommande projekt Då vi inte haft så många tekniska problem under projektets gång så ligger våran fokus på förbättrad gruppkommunikation till framtida projekt. En gemensam arbetsmiljö gör en stor påverkan på kontrollen av vad som görs och när, vi valde att arbeta på valfri plats vilket ledde till att man inte kunde vara helt säker på vart gruppen låg i iterationsprocessen. Vi borde också haft ett system för att se om ett krav inte skulle upfyllas i tid och haft en strategi för att hantera detta. Det fanns tyvärr ingen strategi för detta under projektets gång vilket ledde till en hel del stress över uppgifter som stökade, samt att problemet enbart förflyttades framåt och släpade med i iterationerna. Dokumenten för iterationsplaner och tidsrapporter ser vi också som en viktig del att ha klara så tidigt så möjligt för att underlätta dokumentering, istället för att ändra dessa i mitten av projektets gång. Det ska också klargöras för hela gruppen att dessa dokument redigeras kontinuerligt då de ska fyllas i så fort man är klar med en task/uppgift. Något vi slarvade med i början vilket ledde till mer arbete mot slutet. Vi hade även problem när det gällde att komma i tid till gruppmöten och handledningsmöten. Vi anser att detta hade kunnats lösa genom att man sätter konsekvenser om man är försenad så det inte uppstår i framtiden, till exempel att den som är försenad bjuder alla på kaffe. 19