Faculteit Wetenschappen en Bio-ingenieurswetenschappen Vakgroep Computerwetenschappen
Software Project Management Plan Arno De Witte, Romeo Van Snick, Vincent De Schutter, Silke Verhaeghe, Yannick Merckx Iteratie 1
Academiejaar 2014-2015
Revisies Omschrijving
Datum
Door
Initi¨ele versie Uitgebreid met SCMP en SQAP Uitgebreid voor iteratie 1 Finale versie voor iteratie 1
25/10/2014 04/11/2014 18/11/2014 13/12/2014
Arno Arno Arno Arno
1
De De De De
Witte Witte Witte Witte
Inhoud 1 Introductie 1.1 Doel . . . . . . . . . . . . 1.2 Beperkingen . . . . . . . . 1.3 Deadlines . . . . . . . . . 1.4 Evolutie van dit document
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
. . . .
3 3 3 3 4
2 Referenties
5
3 Definities
6
4 Project Organisatie 4.1 Organistatie naar buiten toe . . . . . . . . . . . . . . . . . . . . . 4.2 Rollen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
7 7 7
5 Management plan 5.1 Opstartplan . . . . . . . . . . . 5.1.1 Stafplan . . . . . . . . . 5.2 Werkplan . . . . . . . . . . . . 5.2.1 Werkactiviteiten . . . . 5.2.2 Planning . . . . . . . . 5.2.3 Communicatie middelen 5.3 Controle Plan . . . . . . . . . . 5.3.1 Requirements controle . 5.3.2 Planning controle . . . . 5.3.3 Budget controle . . . . . 5.4 Risico beheer . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
. . . . . . . . . . .
9 9 9 9 9 10 10 10 10 11 11 11
6 Technisch procesplan 14 6.1 Procesmodel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6.2 Methoden en middelen . . . . . . . . . . . . . . . . . . . . . . . . 14 6.3 Infrastructuurplan . . . . . . . . . . . . . . . . . . . . . . . . . . 14 7 Bijkomende procesplannen 7.1 SCMP . . . . . . . . . . . . . . . . 7.1.1 Configuration Management 7.1.2 SCM . . . . . . . . . . . . . 7.2 Bibliotheken . . . . . . . . . . . . . 7.3 Quality assurance plan . . . . . . . 7.3.1 Documenten . . . . . . . . 7.3.2 Broncode . . . . . . . . . . 7.4 Documentatie plan . . . . . . . . .
2
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
. . . . . . . .
15 15 15 15 18 19 19 20 20
1
Introductie
1.1
Doel
Het doel van dit project is om een publicatiebeheersysteem te bouwen. Het systeem beheert verschillende wetenschappelijke publicaties (zoals artikels, papers e.a.). Gebruikers kunnen zelf publicaties toevoegen, alsook andere publicaties opzoeken. Verder kan er een sociaal netwerk gebouwd worden tussen auteurs. Ook kunnen statistieken over verschillende auteurs, lezers, universiteiten en andere kunnen worden opgevraagd. Als naam voor het project hebben we gekozen voor “Pubdig”. Dit is een samentrekking van de Engelse woorden “Publications” en “Digging”. De symboliek hierachter is het verdiepen in publicaties, waar het systeem mee kan helpen. Het systeem is een webtoepassing die volledig gebouwd is in Javascript en draait dus in een browseromgeving. De toepassing zal naast ondersteuning voor de desktop ook ondersteuning bieden voor mobiele gebruikers.
1.2
Beperkingen
• Enkel gebruik van Javascript, HTML en CSS als programmeertalen. Er mogen wel open-source libraries gebruikt worden. • De backend draait op de Wilma server. • De frontend moet beschikbaar zijn in alle conventionele (mobiele) browsers. • Er moet een website beschikbaar zijn over het project. Hierop kan informatie over de staat en de vooruitgang van het project worden gevonden. • Alle documenten (in pdf formaat) en code moet beschikbaar zijn vanaf de site van het project. • Er moet een overzicht van alle requirements en hun vordering op de website te vinden zijn. • Alle documenten moeten worden opgeleverd in het Nederlands. • Een iteratief ontwikkelingsproces. • Het team bestaat uit vijf studenten van het vak “Software Engineering” [8].
1.3
Deadlines
Omschrijving
Datum
Inleveren SPMP Eerste versie documenten Einde iteratie 1: opleveren code en documenten Presentatie iteratie 1 Einde iteratie 2: opleveren code en documenten Presentatie iteratie 2 Einde iteratie 3: opleveren code en documenten
Woensdag 05/11/2014 Woensdag 19/11/2014 Maandag 15/12/2014 Vrijdag 19/12/2014 Dinsdag 03/03/2015 Woensdag 11/03/2015 Maandag 20/04/2015
3
Omschrijving
Datum
Presentatie iteratie 3 Einde iteratie 4: Finale oplevering. Presentatie iteratie 4
Woensdag 22/04/2015 Vrijdag 15/05/2015 Woensdag 20/05/2015
Hieronder een kort overzicht van alle deliverables die bij elke iteratie moeten worden opgeleverd. • Software Project Management Plan (SPMP) • Software Design Document (SDD) • Software Test Document (STD) • Software Requirements Specification (SRS) • Website over het project (zie beperkingen 1.2) • Source code en dergelijke • Verslagen van vergaderingen
1.4
Evolutie van dit document
Dit document wordt onderhouden door de project manager, Arno De Witte. Wanneer deze niet beschikbaar is zal Romeo Van Snick deze taak op zich nemen als backup project manager. Naargelang het project evolueert, zal dit document worden uitgebreid.
4
2
Referenties
[1] Project website. http://wilma.vub.ac.be/∼se3 1415/ [2] GitHub Repositories. https://github.com/PubDig/ [3] Wilma. http://wilma.vub.ac.be/ [4] JSdoc. http://usejsdoc.org/ [5] Slack. https://slack.com/is/ [6] Trello. https://trello.com/tour [7] Agile Development. http://en.wikipedia.org/wiki/Agile software development [8] Software Engineering. http://www.vub.ac.be/opleiding/fiches/13043 [9] Node.js http://nodejs.org/
5
3
Definities
SPMP Software project management plan SCMP Software configuration management plan SDD Software design document SRS Software requirements specification STD Software test document SQAP Software quality assurance plan Frontend Gedeelte van het project dat in de browser wordt uitgevoerd Backend Gedeelte van het project dat op de server wordt uitgevoerd
6
4
Project Organisatie
4.1
Organistatie naar buiten toe
De klanten in dit project zijn de docenten van het vak Software Engineering [8]: Prof. Dr. Ragnhild Van Der Straeten en Jens Nicolay. Communicatie met de klant gebeurt via email, tijdens de lessen “Software Engineering” of tijdens afspraken. Contact over de requirements zal gebeuren door de requirements manager.
4.2
Rollen
• Project manager – – – – –
Verantwoordelijk voor het maken van SPMP. Leidt de vergaderingen. Inleveren documenten en code. Zorgt voor een goede werking tussen de onderlinge groepsleden. Eindverantwoordelijke voor het halen van deadlines.
• Configuration manager – – – – –
Beheert het version control systeem. Beheert de website. Helpt het team met de gebruikte software en tools. Schrijft het SCMP. Maakt code- en document conventies.
• Design manager – Verantwoordelijk voor het code design van het project. – Schrijft het SDD. • Quality assurance manager – – – –
Staat in voor de kwaliteit van het ontwikkelingsproces. Staat in voor de kwaliteit van de documenten. Staat in voor de kwaliteit van de code. Controleert of de requirements correct in de applicatie worden ge¨ımplementeerd worden en voldoen aan de eisen van de klant. – Staat in voor de kwaliteit van het afgeleverde product. • Test Manager – Beheert de testen die instaan voor de stabiliteit van de code. – Zorgt dat de tests automatisch en regelmatig worden uitgevoerd. – Controleert het resultaat van de testen. Documenteert en rapporteert eventuele problemen zodat programmeurs deze kunnen oplossen. – Verantwoordelijk voor het STD.
7
• Requirements manager – Schrijft het SRS. – Voegt eventuele requirements toe of past huidige aan. – Houdt het team op de hoogte van eventuele wijzigingen. • Secretaris – Neemt notities tijdens de vergaderingen. – Uitschrijven van de verslagen van de vergaderingen. – Communiceert over onduidelijkheden over de organisatie. • Grafisch design manager – Staat in voor het uiterlijk van de toepassing en website. – Maakt wireframes van de diverse pagina’s in het systeem. • Programmeurs – Schrijft de code. – Voorziet zijn deel van de code van documentatie. – Schrijft testen voor de code die hij heeft geschreven. Er is gekozen om de functie van Quality assurance manager en test manager samen te voegen. Dit omdat in de praktijk de kwaliteit van de code nauw in verband staat met de stabiliteit van de code.
8
5
Management plan
5.1
Opstartplan
5.1.1
Stafplan
Het team bestaat uit 5 leden: Arno De Witte, Romeo Van Snick, Vincent De Schutter, Silke Verhaeghe en Yannick Merckx. Dit zijn allemaal studenten computerwetenschappen die het vak “Software Engineering” [8] volgen. Voor elk van de bovenstaande rollen is er telkens ´e´en iemand de hoofdverantwoordelijke. Er is ook steeds een backup, dit wil zeggen dat wanneer de hoofdverantwoordelijke niet in staat is om de rol uit te voeren, de backup hem zal helpen in het uitvoeren van de rol. Opmerking hierbij is dat elk teamlid, naast zijn hieronder genoteerde functie, ook programmeur is. Functie
Persoon
Backup
Project Manager Secretaris Quality assurance manager en Test manager Design manager Configuration manager Requirements manager Grafisch design manager
Arno De Witte Silke Verhaeghe Yannick Merckx Silke Verhaeghe Romeo Van Snick Vincent De Schutter Vincent De Schutter
Romeo Van Snick Arno De Witte Vincent De Schutter Yannick Merckx Arno De Witte Silke Verhaeghe Romeo Van Snick
5.2 5.2.1
Werkplan Werkactiviteiten
In de onderstaande tabel kunnen de verschillende werkactiviteiten gevonden worden. Iteratie 1 Activiteit
Verantwoordelijke
Geschatte werktijd
Effectieve werktijd
Document
Project beheren Configuratie setup Requirements beheren Design Implementatie Tests beheren
Project manager Configuration manager Requirements manager Design manager Programmeurs Test manager
70 uur 5 uur 40 uur 10 uur 70 uur pp. 50 uur
30 10 30 20 60 10
SPMP SCMP SRS SDD Broncode STD
uur uur uur uur uur uur
Als evaluatie hieruit kunnen we besluiten dat de sommige inschattingen zoals project management en testen voor de eerste iteratie niet helemaal correct waren. Maar naar gelang het project vordert, zullen er meer tests zijn en zal de taak van Test manager dus ook zwaarder worden. Voor bijvoorbeeld de configuration manager was er een onderschatting, maar nu het systeem draait zal deze ook een 9
minder zware taak hebben. Over het algemeen waren de inschattingen eerder te hoog. Hier is rekening mee gehouden bij het opstellen van de inschatting voor de volgende iteratie. Iteratie 2 Activiteit
Verantwoordelijke
Geschatte werktijd
Document
Project beheren Configuratie onderhouden Requirements beheren Design Implementatie Tests beheren Wekelijkse vergaderingen
Project manager Configuration manager Requirements manager Design manager Programmeurs Test manager Iedereen
40 uur 2 uur 10 uur 5 uur 70 uur pp. 30 uur 10 uur
SPMP SCMP SRS SDD Broncode STD Vergadering verslagen
5.2.2
Planning
Aan de hand van de bovenstaande werkactiviteiten werd er een visualisatie gemaakt van de planning voor de eerste iteratie. Deze tabel, ook wel een Gantt chart genoemd, geeft het visueel verloop weer van wanneer de verschillende activiteiten uitgevoerd zullen worden. De geschatte werktijd van een activiteit zal dus gespreid worden over de dagen waarop deze activiteit gepland staat. De Gantt chart voor iteratie 2 is te vinden als bijlage van dit document. 5.2.3
Communicatie middelen
Voor de interne communicatie wordt er gebruik gemaakt van Slack [5]. Dit is een berichten systeem waarin er verschillende kanalen kunnen worden aangemaakt voor verschillende onderwerpen. Voor de interne taakverdeling wordt gebruik gemaakt van Trello [6]. De taakverdeling word elke week na de vergadering aangepast. Er wordt ook gebruik gemaakt van de mailinglist om algemenere updates over het project te geven.
5.3 5.3.1
Controle Plan Requirements controle
Wijzigingen aan de project requirements (bepaalt door de klant) zullen steeds worden gereflecteerd in het SRS en op het requirements overzicht op de website. De requirement manager moet de wijzigingen aan de requirements steeds toelichten aan het team op de eerst volgende vergadering. De identifiers van de requirements moeten steeds dezelfde blijven. Zo blijven bestaande referenties naar de requirements steeds correct. Moesten er extra requirements bijkomen of moesten er aanpassingen aan de requirements gebeuren zal in het SRS besproken worden hoe dit het identificeren van de requirements verandert. De klant kan op elk moment de requirements aanpassen of nieuwe requirements toevoegen. De requirements manager zal dit opvangen.
10
5.3.2
Planning controle
Op de wekelijkse vergadering vraagt de project manager steeds naar de vooruitgang van elk teamlid. Er worden elke week doelstellingen afgesproken die door elk teamlid moeten worden behaald. Deze gelden dus ook als deadlines. De project manager zoekt bij mogelijke problemen, bijvoorbeeld het niet halen van deadlines, naar oplossingen. Hij is dus verantwoordelijk voor het halen van de opgelegde deadlines. 5.3.3
Budget controle
Het budget voor dit project wordt uitgedrukt in werkuren. De kost van het project is dus het aantal werkuren aan het project. Op de github [2] staat een intern document waar ieder teamlid noteert hoeveel tijd hij aan een bepaalde taak heeft gespendeerd. Zo kan er worden nagegaan hoeveel tijd er aan verschillende taken wordt gespendeerd. Bij het einde van een iteratie kan dit document dan worden aangepast om zo de effectief gewerkte tijd te vergelijken met de inschatting. Vermits er nog geen ervaring is met het inschatten kunnen deze dus verschillen van de realiteit. Zo kan er in volgende iteraties een betere afschatting worden gemaakt van de kost van dit project.
5.4
Risico beheer
Hieronder een lijst met mogelijke risico’s bij het ontwikkelen van het project. Voor elk risico is er een waarschijnlijkheid (schaal 1-10), impact (schaal 1-10), kost oplossing (schaal 1-10), oplossing en een verantwoordelijke. 1. Uitvallen van een teamlid. • • • •
Waarschijnlijkheid 2 Impact 7 Kost Oplossing 8 Oplossing: Taken worden overgedragen aan backup. Nieuwe backup wordt gezocht voor de functie. • Verantwoordelijke: Project manager. 2. Onvoldoende kennis van Javascript. • • • •
Waarschijnlijkheid 5 Impact 8 Kost oplossing 6 Oplossing: De leden die geen kennis hebben van Javascript schaven deze bij voor 7 oktober. Bij problemen springen de andere groepsleden (met kennis van Javascript) bij. De quality assurance manager besteedt in de eerste iteratie extra aandacht aan de code geproduceerd door deze leden van het team. • Verantwoordelijke: Project manager en quality assurance manager.
11
3. Documenten of code zijn niet tijdig klaar. • • • •
Waarschijnlijkheid 5 Impact 9 Kost oplossing 4 Oplossing: Het opleggen van deadlines. Bij mogelijke problemen licht men de project manager in. Die dan zelf bijspringt of iemand aanduidt om dit te doen. • Verantwoordelijke: Project manager. 4. Verlies van documenten. • • • •
Waarschijnlijkheid 2 Impact 9 Kost oplossing 2 Oplossing: Elk lid zorgt ervoor dat de documenten op de github staan. Zo staan ze gebackupt op Github [2] en de computers van de andere teamleden. • Verantwoordelijke: Project manager. 5. Falen backend Wilma. • • • •
Waarschijnlijkheid 1 Impact 6 Kost oplossing 8 Oplossing: Er wordt een andere server gezocht om de code op te draaien. • Verantwoordelijke: Configuration manager. 6. Kwaliteit van het project is onvoldoende. • • • •
Waarschijnlijkheid 4 Impact 7 Kost oplossing 6 Oplossing: De quality assurance manager controleert wekelijks de kwaliteit van het project. Er worden ook automatische tests uitgevoerd bij het updaten van de code. • Verantwoordelijke: Quality assurance manager. 7. Meningsverschillen • • • •
Waarschijnlijkheid 7 Impact 5 Kost oplossing 4 Oplossing: Er wordt eerst een oplossing gezocht waar de verschillende partijen zich in kunnen vinden. Als deze niet kan gevonden worden, heeft de verantwoordelijke (bijvoorbeeld configuration manager bij de keuze over een tool) altijd het laatste woord. Bij verdere onenigheid, is de project manager verantwoordelijk voor het zoeken van een oplossing. 12
• Verantwoordelijke: Project manager. 8. Onvoldoende domeinkennis (publicaties, conventies, ...) • Waarschijnlijkheid 5 • Impact 8 • Kost oplossing 3 • Oplossing: Er wordt informatie vergaard bij assistenten en professoren over het onderwerp waarmee een probleem is. Vermits dit project in een academische context wordt gemaakt is het raadplegen van deze personen geen probleem.
13
6 6.1
Technisch procesplan Procesmodel
Voor dit project wordt er gewerkt met een iteratief model. Dit volgens de principes van Agile development [7]. Dit wil zeggen dat we steeds kiezen om bij elke iteratie een werkend project af te leveren. We kiezen hierbij om bepaalde requirements niet mee te leveren in een bepaalde iteratie, zo wordt er getracht om de ge¨ımplementeerde requirements zo volledig mogelijk af te hebben. De vooruitgang van het project kan het best gemeten worden aan de hand van werkende software. Er wordt steeds wekelijks vergaderd. Tijdens deze vergadering geeft ieder teamlid een kleine update over de status van zijn stuk, zodat iedereen op de hoogte blijft van de status van het gehele project.
6.2
Methoden en middelen
We gebruiken voor dit project de programmeertaal Javascript. Zowel de frontend en de backend wordt hierin geschreven. Voor de backend wordt gebruik gemaakt van Node.js [9]. Voor het frontend design wordt er gebruik gemaakt van HTML en CSS. Als database gebruiken we MySQL, deze software is beschikbaar op de Wilma server [3]. Als version control systeem gebruiken we git. We gebruiken github [2] als webhost voor onze repository. Er zal een repository worden aangemaakt voor de code en interne documenten en een repository voor de officiele documenten. Verwijzingen naar deze repositories zijn te vinden op de website [1].
6.3
Infrastructuurplan
De backend van het project zal draaien op de Wilma server. Deze wordt aangeboden door de Vrij Universiteit Brussel. De frontend moet kunnen draaien in verschillende browsers (zowel mobiel als desktop). Voor de mobiele browser kan beroep gedaan worden op android toestellen van de klant.
14
7 7.1
Bijkomende procesplannen SCMP
Naast het project management plan die het project en zijn evolutie in de juiste banen leidt, is het nodig ook een configuration management plan op te stellen. Dit document bevat richtlijnen voor het gebruik en de communicatie over code, tools en frameworks. Deze richtlijnen zijn er zowel voor intern gebruik, waar ze zorgen voor een vlotte samenwerking tussen de ontwikkelaars, als voor externe gebruikers van de software, die dankzij de uniforme werkwijze sneller hun weg kunnen vinden in het project. Beslissingen i.v.m. gebruik van frameworks, software en tools worden gaandeweg tijdens de evolutie van het project genomen want het is onmogelijk om alles reeds vooraf vast te leggen. Dit document zal dus nog evolueren naarmate het project vordert. 7.1.1
Configuration Management
De configuration manager is verantwoordelijk voor het toezien op het correct toepassen van de conventies en eventuele problemen of frictie op te lossen. Hij houdt de teamleden op de hoogte van aanpassingen van de richtlijnen en stuurt bij waar nodig. De configuration manager is ook verantwoordelijk voor het correct configureren van de gebruikte tools en frameworks, om zo het werk van de teamleden te verlichten. 7.1.2
SCM
Documenten Interne verslagen en documenten worden in markdown geschreven. Dit is een simpele markup-taal die iedereen snel onder de knie heeft en die weinig vooroordelen heeft over presentatie van de inhoud. Dit laat toe dat de documenten op een eenvoudige wijze omgezet worden naar verschillende formaten zodat die kunnen dienen voor verschillende doeleinden. Dit heeft als voordeel dat de instapkost en het gebruik risico voor markuptalen vermeden wordt. Iedereen kan snel markdown leren. De omzetting gebeurt aan de hand van de pandoc tool. Deze neemt markdown als input en genereert o.a. LaTeX of html documenten. Externe documenten worden in LaTeX geschreven. Markdown is namelijk een te eenvoudige taal om de complexiteit van zulke documenten in uit te drukken. Deze documenten hebben een langere levensduur en de risico’s waarover hierboven gesproken worden, worden dus verspreid. Bovendien werken aan deze documenten vaak meerdere personen samen, ze kunnen elkaars fouten dus snel oplossen. De quality assurance manager kan bij het nagaan van deze documenten steeds fouten aangeven en oplossen. Conventies De conventies waaraan elk teamlid zich moet houden, bevinden zich ook op github. Zo heeft iedereen steeds een overzicht van de huidige 15
conventies en kunnen veranderingen van de conventies transparant worden doorgevoerd. Het onderwerp van deze conventies is voornamelijk code-formattering. Dit is een belangrijk onderwerp omdat het de teamleden toelaat op een gestructureerde wijze aan de code te werken. De codebase blijft netjes en iedereen vindt er zijn weg in. Bovendien helpen goede conventies sommige bugs te vangen (zeker in javascript). Github Om het overzichtelijk delen en beheren van code te vergemakkelijken zal gebruik gemaakt worden van github. Van de teamleden wordt verzocht om de code die ze schrijven regelmatig in te checken zodat iedereen steeds kan beschikken over de meest recente code. De management documenten worden eveneens in github bewaard, zodat ook deze dezelfde voordelen genieten. De code- en de management repositories worden gescheiden gehouden, zodat deze onafhankelijk van elkaar kunnen evolueren. Het is belangrijk dat op github enkel source-documenten worden bijgehouden, en dus nooit gegenereerde of gecompileerde documenten. Dit voorkomt dat er verschillende (tegenstrijdige) versies van een zelfde document aanwezig zijn in de repository. Als iemand een document in een bepaalde (gecompileerde) vorm nodig heeft, kan zij het altijd zelf compileren aan de hand van de correcte tool. Om te verzekeren dat de code die aanwezig is in de repository zeker voldoet aan de conventies die zijn vastgelegd, wordt gebruik gemaakt van het node-hooks pakket. Dit laat de contributors toe op een eenvoudige en geautomatiseerde wijze bepaalde scripts over de documenten die gecommit worden te laten lopen. Met name wordt er gebruik gemaakt van beautify.hks, een script dat de formattering van javascript bestanden normaliseert. De configuratie voor deze scripts bevindt zich ook in github, zodat deze gedeeld is tussen alle gebruikers (wat uiteraard belangrijk is). Bovendien is dit nog eens een extra specificatie van de syntax-conventies. API documentatie Omdat dit van uiterst belang is voor de correcte werking van het afgeleverd product wordt het protocol dat gebruikt zal worden tussen de frontend en de backend expliciet beschreven. Dit gebeurt aan de hand van een RAML-specificatie. RAML is een specificatie-tool die toelaat api’s te specifieren en te documenteren. De api-documentatie zal steeds te vinden zijn op de website. De specificatie beschrijft welke endpoints er zijn alsook wat de verwachte parameters en return waarden zijn. Dit laat toe dat het backend team de correcte functies implementeert en dat het frontend team de correcte functies op een correcte manier gebruikt. De specificatie zal uiteraard ook evolueren met de tijd, maar dit wordt (waar mogelijk) altijd gedaan met oog op compatibiliteit met oudere versies. Zo moet reeds geschreven code niet meer aangepast worden. Website Er wordt ook een website [1] onderhouden, hierop bevindt zich de meeste informatie die met de management van het project te maken heeft. De
16
documenten die zich op deze website bevinden worden automatisch gecompileerd uit de documenten die zich in github bevinden. Dit gebeurt elke keer wanneer iemand ze aanpast. Zo blijven de documenten automatisch up-to-date en wordt het werk van de teamleden verlicht. De configuration manager is verantwoordelijk voor het onderhouden van de scripts die deze automatisering toelaten. npm en package.json Node.js voorziet een goede toolchain die het toelaat op een eenvoudige wijze het project te onderhouden en te bouwen: npm1 . Deze maakt gebruik van een configuratie bestand package.json. Dit bestand bevat o.a. een lijst van gebruikte packages. Dit laat toe dat elke gebruiker van de code enkel nog npm install moet uitvoeren en dat hij dan zonder meer het project kan gebruiken: npm is verantwoordelijk voor het ophalen van alle packages. Ook andere functionaliteit wordt onder npm ondergebracht. Zo kan de server gestart worden met npm start en kunnen de test uitgevoerd worden a.d.h.v. npm test. Dit alles laat toe dat het project na elke push op de github account kan worden gebouwd op de backend server of getest op de CI server (zie later). Het vereenvoudigt ook de samenwerking aangezien teamleden niet alle scripts of moeten kennen. gulp Waar npm voornamelijk instaat voor het onderhouden van bibliotheken en het runnen van scripts, staat gulp2 in voor het bouwen van de frontend code. Gulp wordt vooral gebruikt om transformaties te doen op frontend code zoals samenvoegen en minifien (verkleinen) van javascript bestanden, afbeeldingen web-klaar maken, Reactjs-code compileren naar javascript etc. Dit alles gebeurt in een fractie van een seconde zodat gulp ook tijdens het coderen gebruikt kan worden. Er is een gulp-taak die verantwoordelijk is voor het detecteren van aanpassingen in files die dan de juiste taken oproept om de “gegenereerde” code up te daten. Dit heeft als voordeel dat een frontend programmeur tijdens het programmeren steeds ook de uiteindelijke frontend code zoals die bij de eindgebruiker terecht komt voor handen heeft en er dus later geen inconsistensies kunnen optreden die mogelijks te verwachten zijn mocht de code slechts in de finale stap (bij het uitrollen van de software) zo behandeld worden. gulp is zelf ook een npm bibliotheek en het is dus triviaal om het te installeren (npm install zoals hierboven). Travis CI Er wordt gebruik gemaakt van een continuous intergration server, met name Travis CI3 . Deze server voert na elke push op github de tests (npm 1 https://www.npmjs.org 2 http://gulpjs.com 3 https://travis-ci.org
17
test) uit en maakt een verslag op. Dit zorgt ervoor dat er steeds recente testdata is en dat van elke gefaalde test geweten is door welke commit hij veroorzaakt wordt. Bugtracker Github bevat standaard een bugtracker die eenvoudig in gebruik is. Deze laat zowel teamleden als anderen toe om bugs en issues aan te kaarten. In de interface van github is het bovendien eenvoudig om bepaalde code aan bugs en bugfixes te linken wat alles erg overzichtelijk maakt. Pubdig zal van deze bugtracker gebruik maken doorheen het project. Node.js Dit is de server software waarop dit systeem draait. Node.js evalueert javascript en biedt de mogelijkheid om http requests te verwerken. Dit is de meest gebruikte server software die gebruik maakt van javascript (wat een beperking van dit project is). Er zijn heel erg veel uitbreidingen en bibliotheken voor deze software wat het een logische keuze maakt.
7.2
Bibliotheken
Doorheen dit project zal gebruik gemaakt worden van verschillende bibliotheken. De meeste hiervan zijn niet van fundamenteel structureel belang voor het project. Ze bieden enkel implementaties voor bepaalde functionaliteit zodat deze niet door het pubdig team heruitgevonden moeten worden (bijvoorbeeld een bibliotheek die met de SQL database praat) en zouden in principe uitwisselbaar moeten zijn. Sommige bibliotheken bieden echter meer dan enkel dit, ze bieden ook een structurele meerwaarde en bieden een “architectuur” aan waarmee de projecten kunnen worden opgebouwd. Er wordt gebruik gemaakt van twee zulke bibliotheken: Express voor de backend een React.js voor de frontend. Express Express is een infrastructuurlaag bovenop degene die reeds aanwezig is in node.js en die veel extra voordelen biedt. Express deelt de backend functionaliteit op in verschillende handlers die elk verantwoordelijk zijn voor het behandelen van http-requests die gebeuren naar de hun eigen route (url). Daarbovenop voorziet Express ook nog het concept van middleware: dit zijn functies die alle requests manipuleren, ongeacht naar welke route ze uiteindelijk gestuurd worden. Deze structuur promoveert twee dingen: er is een strikte scheiding van verantwoordelijkheid tussen de verschillende handlers en routes en code-duplicatie wordt expliciet tegengegaan door de gemeenschappelijke code in de middleware te stoppen. React.js De belangrijkste bibliotheek die aan de frontend gebruikt zal worden is React.js4 Dit is een bibliotheek die het schrijven van UI-code vereenvoudigt door het concept van componenten te introduceren. 4 http://facebook.github.io/react/
18
De user interface is een van de belangrijkste verantwoordelijkheden van de frontend code en het is dus belangrijk hiervoor een goede structuur te hebben. React helpt hierbij door de verantwoordelijkheden op te splitsen in de componenthi¨erachie. Elke component heeft als het ware slecht een verantwoordelijkheid: zijn eigen toestand bewaren en weten hoe hij zichzelf “rendert” (tekent). De resulterende structuur gelijkt sterk op die van het Chain-of-command patroon dat reeds bekend is in de wereld van de computerwetenschappen. Elke component heeft een bepaalde levenscyclus en het is aan de programmeur om voor elke component voor elke stap in de cyclus een implementatie te geven. Omdat elke component aan dezelfde eisen voldoet zijn componenten erg vrij te samen te stellen (hun interface is steeds dezelfde). React biedt bovenop deze conceptuele aspecten ook faciliteiten om eenvoudig html te genereren van bepaalde data en dit op een effici¨ente wijze. Dit neemt een groot deel van de zorgen van de frontend programmeurs weg zodat deze zich kunnen concentreren op belangrijkere zaken. Bovendien kunnen de componenten ook in de backend gebruikt worden om daar de html te renderen. Dit voorkomt dat er code-duplicatie ontstaat.
7.3
Quality assurance plan
Op de vergaderingen wordt er besproken of iedereen zijn taken heeft kunnen voltooien. Indien er taken niet zijn uitgevoerd of voltooid, wordt de persoon in kwestie bijgestuurd door de project manager en/of wordt er besproken met het team hoe deze persoon ondersteund kan worden, om zo terug op schema te geraken. 7.3.1
Documenten
Er worden 4 documenten opgeleverd per iteratie die door telkens een andere persoon worden opgesteld. Deze 4 documenten zijn het SPMP, STD, SRS, SDD, en als onderdeel van het SPMP: het SQAP en SCMP. Omdat ieder document opgesteld wordt door zijn respectievelijke verantwoordelijke, zijn er door de Quality Assurance Manager standaarden vastgelegd i.v.m structuur en opmaak. Deze richtlijnen leggen vast dat alle documenten geschreven worden in LaTeX en hun structuur, opmaak, spelling en zinsbouw voor de definitieve oplevering nog eens moet worden gecontroleerd door de Quality Assurance Manager. Hiervoor moeten er uiteraard interne deadlines worden vastgelegd, ruim voldoende voor de offici¨ele deadline, die de Quality Assurence Manager de tijd geeft om alles te controleren of indien nodig in te grijpen. Alle documenten worden verzameld op Github. Wanneer een document klaar is volgens de verantwoordelijke wordt dit gecommuniceerd via onze communicatiekanalen en kan de Quality Assurence Manager aan zijn controle beginnen. Het is de verantwoordelijkheid van de Quality Assurance Manager om documenten te corrigeren. Na goedkeuring van de documenten worden deze als voltooid beschouwd en wordt dit wederom gecommuniceerd via onze communicatiekanalen.
19
7.3.2
Broncode
Documentatie en commentaar Er wordt verwacht dat de programmeurs kwalitatieve code schrijven, d.w.z. mooie, leesbare code met voldoende commentaar. Bovendien moet code voldoende gedocumenteerd worden d.m.v. een complete documentatie. Samen met het commentaar bij de broncode moet deze documentatie voldoende zijn voor de Quality Assurance Manager om code te lezen en te begrijpen. Wanneer de programmeur zijn vooropgestelde opdracht heeft afgewerkt, wordt de code gecontroleerd door de Quality Assurence Manager. Wanneer er iets onduidelijk is in de code, moet de Quality Assurence Manager, met de programmeur in kwestie, in overleg treden om deze onduidelijkheden uit te klaren. Wanneer de code niet voldoet aan de vooropgestelde eisen, zal de programmeur desondanks nog moeten proberen de vooropgestelde eisen te behalen door zijn code of commentaar te verbeteren. Testing De Quality Assurance Manager staat in voor het nakijken van alle tests en zal er op toezien dat er voldoende geautomatiseerde tests aanwezig en valabel zijn. Er wordt gebruik gemaakt van het testingframework Mocha en wordt verder ondersteund door Chai en Sinon. Uiteraard wordt er ook op toegezien dat alle tests slagen en geheel voldoen aan het Software Test Document (STD). Dit wil zeggen dat ook de tests van een hoge kwaliteit moeten zijn. Ze moeten dus aan dezelfde standaarden voldoen als de code.
7.4
Documentatie plan
Alle documenten zijn steeds terug te vinden op de website [1] van het project. Bij elke iteratie moeten volgende documenten worden meegeleverd, in de lijst hieronder kan ook de verantwoordelijke voor dit document gevonden worden. • • • •
SPMP, project manager SRS, requirement manager SDD, design manager STD, test manager
In het SPMP kan ook een hoofdstuk over de configuratie worden gevonden alsook een hoofdstuk over quality assurance. Deze vervangen het SCMP en SQAP. Deze hoofdstukken worden opgesteld door respectievelijk de configuration manager en de quality assurance manager. Voor elke vergadering wordt steeds een klein verslag opgesteld. Dit bevat telkens agendapunten en TODO’s die voor aanvang van de vergadering worden aangemaakt (meestal op de vergadering ervoor). Tijdens de vergadering wordt het verslag dan aangevuld met de zaken die zijn besproken op deze vergadering. Dit document wordt opgesteld door de secretaris. De code zal gedocumenteerd worden volgens de JSdoc [4] standaard. Er is een intern document gemaakt zodat de documentatie van de code consistent is bij elk teamlid.
20
