FÉLÉVES FELADAT KÖVETELMÉNYEK

Programozás III.

Git / StyleCop / DoxyGen / Sandcastle

v0.95

FÉLÉVES FELADAT KÖVETELMÉNYEK A Programozás III. tárgyon belül elvárás egy egyszerű játékprogram elkészítése, amely - Egyszerű felhasználói interakcióval (egérrel/billentyűzettel) vezérelhető logikai/ügyességi játék. - Teljesíti a rétegek szétválasztásának alapelvét (üzleti logika leválasztása, valamint a WPF kód MVVM elvű szétválasztása). - Megjelenítés Shape-ek / DrawingImage-ek / FrameworkElement segítségével. - Játékfejlesztő framework (pl. XNA, Unity) nem használható! - Megjelenítési framework (pl. SDL, DirectX, OpenGL, Vulcan) használható, de az emiatt a megjelenítésre fordítandó és a keretrendszerrel megspórolt időt a játék logikájára kell ráfordítani! Határidők: - A 2 oldalas specifikáció leadásának határideje: október 2. éjfél (szabályok, felhasználói interakciók lehetőségei, 1 kezdetleges képernyőterv, bitbucket projekt címe) - Leadási határidő (program, valamint a hozzá tartozó dokumentációk): november 25. éjfél - Pótleadási határidő: december 1. éjfél - Védés: gyakorlatvezető döntése alapján vagy a második zárthelyi alatt, vagy a pótzárthelyi alatt, vagy külön időpontban - Verseny: december 20. 10:00 A jól sikerült munkák bemutathatóak a félév végén megrendezett vizuális alkalmazásfejlesztési versenyen, ahol a díjazottak az elértnél egy vagy két osztályzattal jobb érdemjegyet, vagy akár a szakmai szigorlat beugrójának szoftveres része alóli felmentést is kaphatnak. Elvárások a feladat beadásakor: - bitbucket.org -on hostolt GIT projekt, teljes és újrafordítható forráskóddal o A repository neve a hallgató neptun kódját tartalmazza: OENIK_Prog3_2016osz_NEPTUNKÓD o A projektben látszódnia kell a folyamatos fejlesztésnek és haladásnak; ne a leadási határidő előtti 1-2 commitból álljon a verziókövetés! o Bár a verziókövetés tipikusan CSAK szöveges állományokra vonatkozik (képeket nem verziókövetünk!), most a repository-nak mindent tartalmaznia kell, ami a játék működéséhez szükséges - StyleCop szerint valid forráskód - CHM vagy HTML vagy PDF formátumú fejlesztői dokumentáció - Felhasználói dokumentáció (PDF formátumban): címoldal + minimum 3 oldal: játékszabály, irányítási lehetőségek, képernyőképek (minimum 1, és maximum N-3 darab, ahol N=oldalszám)

2016-09-12

1. oldal

Programozás III.


v0.95

GIT QUICKSTART A Git egy elosztott verziókövető rendszer, amelynek segítségével lehetőségünk van a forráskódunk központi kezelésére; valamint a változások megbízható követésére (annak nyilvántartására, hogy melyik file mikor, hogyan, és ki által módosult). Ezt olyan módon éri el hatékonyan a rendszer, hogy nem minden file minden állapotát menti el, csak az egyes változatok közötti különbséget. A Git elosztott működése abban nyilvánul meg, hogy a „klasszikus” verziókövetőkkel szemben (CVS, SVN) nem csak egy központi tárban tárolódik a forráskód file-jainak módosítási története, hanem egy helyi tárban is. Ennek megfelelően, Git esetén külön kell választani a helyi tárat (local repository) és a távoli tárat (remote repository). Harmadik tárként a helyi éppen aktuális változatot (working copy) szokás említeni. Az alapvető Git műveleteket az alábbi táblázat foglalja össze: ADD

COMMIT PUSH FETCH MERGE

PULL

A woking copy–ból file hozzáadása azon file-ok közé, amiken a változások követése aktív / módosult file-ok kijelölése a következő commithoz A working copy-ban lévő módosulások (tartalmi módosítás, ADD, file törlése) eltárolása a local repository-ban A local repository commitjainak feltöltése a remote repository-ba A remote repository commitjainak letöltése a local repository-ba, a working copy módosítása nélkül Ágak egyesítése (pl. a local repository-ban FETCH után egyből két ág van: a saját fejlesztési ág, és a remote repository-ból letöltött ág). Amennyiben az ágak között ellentmondás van (ugyanazon file különböző módosítása), akkor ezt kézzel javítani kell. Emellett, a BRANCH / CHECKOUT utasításokkal lehet új ágat létrehozni, mindegyik ág a kód egy változata, illetve sokszor minden új feature egy-egy új ágat jelent (ld. "A successful git branching model", nvie.com; EZ NEM TANANYAG) FETCH + MERGE

Egy tipikus fejlesztési folyamat a következőképp néz ki: 1. A fejlesztő a nap elején először is egy PULL utasítással letölti a remote repository korábbi módosításait a local repository-ba 2. Az esetleges conflictokat kézzel megoldja 3. Elkezd dolgozni egy új feature-ön / elkezd kijavítani egy hibát (előbbi esetben tipikusan új branch létrehozásával) 4. Egy-egy munkafolyamat végén COMMIT utasítással rögzíti a módosításokat (ez akár file-onként is lehet, de akár 10 file-t is jelenthet, a „one workitem” definíciójától függően. Alapvetően a cél sok kis committal dolgozni, és beszédes commit üzenetekkel. Az az alapelv, hogy minden commit csak egy dolgot javít / ad

2016-09-12

2. oldal

Programozás III.


v0.95

hozzá a kódhoz: „If you have to put the word "and" or "also" in your summary, you need to split it up”, ez az örök aranyszabály). 5. A nap végén/az adott feature, illetve bugfix befejezésekor ismét PULL, és a conflictok kézzel történő megoldása 6. PUSH, és jöhet a következő ticket/munkafolyamat/bugfix/feature…

A git használata Visual Studio alatt 1. A javasolt GIT szerveroldali rendszer, amit a félév során használni fogunk: bitbucket.org. Céljainknak a github.com is jó lenne, de ott minden projekt publikus, csak a fizetős felületen lehet privát projektet létrehozni. Emellett bármilyen más privát Gitlab telepítés is jó lenne, de) az egyetemi projekthez a bitbucket weboldalt kell használni. 2. Bitbucket regisztráció, aktiváció, bejelentkezés, majd ezután jöhet a repository létrehozása: https://bitbucket.org/repo/create. Issue tracking létrehozása javasolt, de nem kötelező.

2016-09-12

3. oldal

Programozás III.


v0.95

3. A létrehozás után a projekt „Repository setup” oldalára jutunk, ahol az „I’m starting from scratch” linket kell kiválasztani. Itt látszik a repository GIT címe is: https://[email protected]/anoftc/nik_test.git 4. Visual Studio-ban Tools/Options/Source control/Plug-in selection: itt a GIT legyen kiválasztva. VS 2013+ esetén ez már alapértelmezetten telepített. VS2012 esetén: https://visualstudiogallery.msdn.microsoft.com/abafc7d6-dcaa-40f4-8a5ed6724bdb980c

)

5. Solution mentésekor (vagy már létrehozáskor) be kell jelölni az „Add to source control” checkboxot. Ebben a dokumentumban végig ebben a WPF alkalmazáson belül fogunk dolgozni.

2016-09-12

4. oldal

Programozás III.


v0.95

6. View/Team Explorer ablakon belül válasszuk ki a „Settings” menüelemet:

7. Ezután „Git settings”. Itt a GIT commitokban lévő adatokat adjuk meg. Javasolt (de nem kötelező), hogy az email cím a Bitbucket regisztrációval azonos email cím X legyen.

8. Ezután gomb, majd „Changes”, itt tudjuk a változásokat rögzíteni a repository-ban:

9. A módosítási üzenet (kötelező) megadása után mehet a gomb, ez a helyi repository-ban tárolja a módosításokat (COMMIT):

2016-09-12

5. oldal

Programozás III.


v0.95

10. A gomb melletti kis nyíl további 2 lehetőséget rejt magában: X

Commit = Helyi repository-ban való tárolás Commit and Push = Commit után a távoli repository-ban való tárolás (PUSH) Commit and Sync = Commit után a távoli repository módosításainak lekérése és egyesítése a helyi repository-val (PULL), majd ezután egy PUSH Ha csak a gombot nyomjuk meg, akkor a VS figyelmeztet, hogy ez csak a helyi repository-t változtatta (VS2015 esetén ez az „első commit” lépés nem feltétlenül szükséges, ha a VS automatikusan rögzítette az első COMMIT-ot): • • •

11. Sync esetén az alábbi ablak jelenik meg, ahol meg kell adni a Bitbucket oldalán látható repository címet:

2016-09-12

6. oldal

Programozás III.


v0.95

12. után bekéri a Bitbucket usernevünket és jelszavunkat. Ez után a Visual Studioban láthatjuk a sikeres PUSH-t, és a Bitbucket oldalon láthatjuk, hogy a repository oldala megváltozott:

)

2016-09-12

7. oldal

Programozás III.


v0.95

13. Változások ezután két helyről jöhetnek: a saját VS verziónkból vagy kívülről (más fejlesztőtől / akár a Bitbucket webfelületéről is). Külső módosítás esetén a saját helyi repository-t frissíteni kell (PULL) mielőtt feltöltenénk a módosításokat (PUSH); és amennyiben a külső módosítás és a saját módosítás ugyanazt a file-t érinti (CONFLICT), akkor ezt (többnyire kézzel, nagy odafigyeléssel) javítani kell. 14. Külső módosítást szimulálunk: módosítsuk a repository-t a Bitbucket weboldalon! ) Adjunk hozzá egy README file-t („Create a README”), ahogy azt a weboldal jelzi is nekünk, hogy ennek jelenléte javasolt a repository-ban.

A commit üzenet default lesz:

2016-09-12

8. oldal

Programozás III.


v0.95

15. Ezután a Visual Studio –ban lehetőségünk van a korábban említett SYNC vagy PULL lehetőségek mellett a FETCH műveletet is kiválasztani: a FETCH nem változtatja a helyi working copy-t, csak a remote repository állapotát tölti le onnan. Ezt elég ritkán használjuk, a SYNC a legjobb választás az esetek nagy részében (persze CONFLICT esetén a SYNC helyett jobb a FETCH, ez után meg tudjuk nézni a hiba okát, és a kézzel javítás után jöhet a SYNC).

16. Saját módosítást szimulálunk: adjunk hozzá az ablakhoz egy gombot, és ehhez egy Click eseménykezelő metódust. A Solution Explorer kicsi ikonokkal jelzi a file-ok állapotát (https://msdn.microsoft.com/en-us/library/ms181372%28v=vs.90%29.aspx)

2016-09-12

9. oldal

Programozás III.


v0.95

17. Ezután a „Team Explorer” ablak „Changes” menüpontjában mehet a COMMIT

)

18. Újabb módosítás (ezúttal csak az eseménykezelőben), újabb COMMIT:

2016-09-12

10. oldal

Programozás III.


v0.95

)

19. Ezután jöhet egy SYNC, és a webfelületen is látjuk a COMMIT history-t:

2016-09-12

11. oldal

Programozás III.


v0.95

)

2016-09-12

12. oldal

Programozás III.


v0.95

20. A weboldal bal menüjében a Settings menüre kattintva, majd az „Access Management” almenüponttal lehet más felhasználóknak jogosultságot adni. Elvárt a saját repository-hoz ADMIN jogosultságot adni az oktató felé

)

Ez a dokumentum csak az alap GIT műveleteket mutatja be. Az igazán jó verziókezelő rendszerek (GIT, TFS) nagy erőssége abban rejlik, hogy képesek több kód ágat (BRANCH-et), valamint az ágak szétválását és egyesítését (FORK, MERGE) hatékonyan kezelni. A hallgatóktól az ágak használata nem elvárt, viszont egy céges környezetben csak a tapasztalt vezető programozóknak van a fő (master) ágra vonatkozóan MERGE joguk, amúgy mindenki a saját fejlesztői ágán dolgozik.

2016-09-12

13. oldal

Programozás III.


v0.95

Egyéb olvasnivalók: • https://hu.wikipedia.org/wiki/Verzi%C3%B3kezel%C3%A9s • https://hu.wikipedia.org/wiki/Git • http://blog.osteele.com/posts/2008/05/my-git-workflow/ • http://nvie.com/posts/a-successful-git-branching-model/ • https://tanarurkerem.hu/git-suli/ • SourceTree (GIT GUI) • Tortoise GIT (GIT GUI) • https://confluence.atlassian.com/bitbucketserver/basic-git-commands776639767.html (basic GIT commands: Team Explorer / Changes / Actions / Open Command Prompt)

)

2016-09-12

14. oldal

Programozás III.


v0.95

STYLECOP QUICKSTART A StyleCop egy VS plug-in, amelynek segítségével lehetőségünk van arra, hogy a forráskódunkban lévő stilisztikai / dokumentációs hibákat megtaláljuk. Telepítése: VS Gallery-n keresztül (Tools / Extensions and Updates) vagy inkább a hivatalos oldalon keresztül: https://stylecop.codeplex.com/ (a VS gallery csomagot más tartja karban, és mindig néhány verzióval a hivatalos verzió mögött van). A telepítő next-next-next stílusú, könnyen telepíthető. C# projekt megnyitása utána a projektre jobb egérgombbal kattintva meg kell jelennie egy „Run StyleCop” és egy „Run StyleCop (Rescan All)” menüpontnak, ezek futtatják a projekten a StyleCop analízist. Javasolt egyből egy „Run Stylecop (Rescan All)” majd „StyleCop settings” –t választanunk, majd az gombra kattintva így egyből elmenteni a beállítás file-t. Ezek hatására egy „StyleCop.Cache” és egy „Settings.StyleCop” file jön létre a projekt könyvtárán belül. A StyleCop hibákat fordítási hibaként jeleníti meg a rendszer, minden lépés után a „Run StyleCop (Rescan All)” lépést hajtsuk végre; látni fogjuk, ahogy folyamatosan csökken a hibák száma. 1. Az assemblyInfo.cs állományban talált hibák minket nem érdekelnek. A file elejére ) szúrjunk be egy sort: // 2. Az app.xaml.cs állományban lévő hibák a következőek: • SA1200: using tagok javasolt helye: névteren belül • SA1650: helyesírási hiba („xaml”) • SA1633: file header hiányzik (Mindegyik hibáról a StyleCop oldalán részletes leírást találunk, például http://stylecop.soyuz5.com/SA1200.html) 3. Az első két hibával lehet vitatkozni, hogy szükségesek –e. Kapcsoljuk ki őket: StyleCop Settings / „Find” szövegdobozba írva tudunk keresni:

2016-09-12

15. oldal

Programozás III.


v0.95

)

4. , majd a file headert is megírhatjuk (opcionális, akár ki is kapcsolhatjuk a szabályt): //----------------------------------------------------------------------// // No copyright (public domain) // //-----------------------------------------------------------------------

5. , már csak a MainWindow.xaml.cs file-ban van hiba • SA1633: File header • SA1600: Dokumentáció hiánya (FONTOS! Minden publikus/internal láthatóságú osztály, metódus, tulajdonság előtt KÖTELEZŐ a dokumentáció: a metódus fölötti sorba három „/” jelet írva automatikusan legenerálja a Visual Studio a dokumentációs kommenteket) • SA1126: minden metódusnak legyen prefixe (PéldánySzintűMetódus() helyett this.PéldánySzintűMetódus() – Esetleg kikapcsolható) • SA1005: Kommentjel után („//”) javasolt a szóköz • SA1642: kötelező konstruktor komment bevezető szöveg – Esetleg kikapcsolható

2016-09-12

16. oldal

Programozás III.


v0.95

6. Ezeket javítsuk ki: //----------------------------------------------------------------------// // No copyright (public domain) // //-----------------------------------------------------------------------

7. Rescan All után:

) ------ StyleCop completed -----========== Violation Count: 0 ==========

8. Team Explorer / Changes menüpont Adjuk hozzá a local repository-hoz a Settings.StyleCop állományt, ezután COMMIT, majd pedig SYNC. A Bitbucket oldalon is látszik a módosítás.

2016-09-12

17. oldal

Programozás III.


v0.95

)

2016-09-12

18. oldal

Programozás III.


v0.95

DOXYGEN/SANDCASTLE QUICKSTART A fejlesztői dokumentáció részét képezi a kézzel írt dokumentáción/diagramokon túl a jól dokumentált forráskódból automatikusan generált dokumentumok. Erre az egyik eszköz a DoxyGen (http://www.stack.nl/~dimitri/doxygen/download.html). 1. A DoxyGen letöltése és kitömörítése után igazából a doxygen.exe, libclang.dll, illetve a HTML Help Workshop telepítése szükséges. 2. A DoxyGen könyvtárban hozzunk létre egy wpf1.config file-t. Az összes konfigurációs beállítás (van jó sok: https://www.stack.nl/~dimitri/doxygen/manual/config.html) nem szükséges nekünk, csak az alábbiak: #Projekt neve PROJECT_NAME = "SZABOZS WPF1" #Kimeneti könyvtár OUTPUT_DIRECTORY = DOCS/ #Minden file használata EXTRACT_ALL = YES #Bemeneti könyvtár INPUT = c:\szabozs\WpfApplication1 #Számunkra érdekes file-ok FILE_PATTERNS = *.cs #Rekurzív? ) RECURSIVE = YES #CHM formátumot is akarunk? GENERATE_HTMLHELP = YES #CHM filenév CHM_FILE = wpf1.chm #HHC (HTML Help Workshop Compiler) helye HHC_LOCATION = "c:\utils\HTML Help Workshop\hhc.exe" #Fa struktúra GENERATE_TREEVIEW = YES

Értelemszerűen a kívánt sorokat módosítsuk igény szerint. Az egyik hiányzó feature az a PDF generálás lehet, ehhez valamilyen TeX fordító és PDFLATEX állomány kell (pl. http://miktex.org/download, 188MB a portable edition…) 3. Hozzunk létre egy doxygen.bat állományt, benne az alábbi két sorral: RD /S /Q DOCS doxygen.exe wpf1.config

4. Ez után a doxygen.bat állomány futtatásának hatására elkészül a HTML és a CHM formátumú dokumentáció. Figyeljünk rá, hogy a dokumentáció csak a PUBLIKUS tagokat tartalmazza, ezért a BigButton_Click eseménykezelőt publikussá tettük a screenshotok elkészítéséhez

2016-09-12

19. oldal

Programozás III.


v0.95

)

2016-09-12

20. oldal

Programozás III.


v0.95

A DoxyGen előnye, hogy open source, és szinte minden programozási nyelvet támogat. Sokkal jobban egyénre szabható, ugyanakkor a száznál több konfigurációs beállítás átlátása bonyolult, és kifejezetten nehéz lehet mindent komponenst megfelelően összeilleszteni. Emellett, nem tud beépülni a Visual Studio-ba, ami az alternatíva legnagyobb előnye. Egyik alternatívája a korábban (2010 júniusáig) Microsoft fejlesztésű, azóta függetlenné vált Sandcastle Help File Builder. Csak felügyelt nyelveket támogat, gyakorlatilag reflexióval szedi ki a szükséges tagokat (nem a forráskódot elemzi, mint a DoxyGen). A projekt jelenleg a https://github.com/EWSoftware/SHFB oldalról tölthető le, valamint NuGet csomagként is (ez utóbbi nem javasolt, kb 1gb méretű extra könyvtárat rak bele a projekt packages könyvtárába, és sokkal nehezebb működésre bírni). Mivel a Sandcastle gyakorlatilag a solution-ben egy extra projektként fog létezni, így könnyen integrálható meglévő solution-be, és a meglévő verziókezelő módszerekkel is jól együtt tud működni. 1. https://github.com/EWSoftware/SHFB/releases oldalról installer letöltése. 2. Next-next-next stílusú telepítés, lehetőségünk van itt is letölteni a HTML Help Compiler-t, illetve külön kell a „Sandcastle Help File Builder”-t; a Visual Studio Extension-t; valamint a Sandcastle MAML extrákat (MAML = Microsoft Assistance Markup Language) telepíteni. 3. A 2015.7.25.0 verzió óta csak a VS2013, VS2015 verziókat támogat a Visual Studio Extension! VS2010 és VS2012 verziókhoz a 2015.5.2.0 szükséges. 4. Ezután a Visual Studio solution-ünkben kell új „Sandcastle Help File Builder” projektet hozzáadni

2016-09-12

21. oldal

Programozás III.


v0.95

5. Az új projektben a „Documentation Sources” menüelemre jobb katt, majd „Add documentation source”, itt hozzá tudunk adni meglévő CSPROJ vagy EXE/DLL állományokat. Adjuk hozzá a WPF alkalmazásunk CSPROJ állományát ⏰Ϸ

6. Engedélyezni kell a WPF alkalmazásunknál a külön XML dokumentációs file generálását (a project properties ablakon belül):

2016-09-12

22. oldal

Programozás III.


v0.95

7. A ContentLayout.content állomány szerkesztésével tudjuk befolyásolni a CHM állomány egyes részeit; a bal menüben egyes elemekre történő dupla kattintással a megfelelő AML állományt (CHM oldalt) lehet szerkeszteni. 8. Ez után a Documentation1 projektre jobb kattintás, majd „Build”. Egy kis várakozás után az alábbi sorokkal kell záródnia az Output ablaknak: Completed The help file is located at: 趰ӻ C:\szabozs\WpfApplication1\Documentation1\Help\Documentation1.chm Build details can be found in C:\szabozs\WpfApplication1\Documentation1\Help\LastBuild.log ========== Build: 1 succeeded or up-to-date, 0 failed, 0 skipped ==========

9. Elkészült a CHM állomány:

2016-09-12

23. oldal

FÉLÉVES FELADAT KÖVETELMÉNYEK

Recommend Documents