Merge branch 'develop' into 'master'

Develop See merge request !2

Merge branch 'develop' into 'master'
Develop See merge request !2
Görcsös Zoltán
2 parents 58827e5c a9903bc8
Showing 5 changed files with 102 additions and 0 deletions Show diff stats
README.md
contribution-branching-model.PNG
contribution-branching-model.websequence
contribution.md
rules.png
@@ -0,0 +1,38 @@
+**v1.0.0**
+
+*#mainteiner:* @zgorcsos
+
+![][#headerpic]
+
+# devprocdoc = Developer Process Documentation
+> A repository alatt vezetjük a Vrh fejlesztési folyamatainak dokumentációját.
+
+## Szabályok:
+* A dokumentáció **kizárólag** markdown alapú!
+* A dokumentáció organizációja **könyvtárakra** törve történik
+* Az MD fájlokban használt képeket a **web.vonalkod.hu** ftp szerveren a fejlesztes/devprocdoc alá kell feltölteni. Az ftp elérési módja [ezen][#webvonalkodhuftp] a Redmine tudástár oldalon található. Az ide feltöltött fájlokat a http://web.vonalkod.hu/fejlesztes/devprocdoc/továbbiútvonal/fájlnév formában hivatkozuk a dokumentációban. Az ftp szerveren a devprocdoc repoisitory-val egyező könyvtár struktúrát kell kialakítani a devprocdoc könyvtár alatt!
+* A fenti feltöltött, és az md fájlokban hivatkozott képeket a repository-hoz is hozzáadjuk!
+* A diskurzus a dokumentációk tartalmáról **kizárólag** itt történik! 
+    * Használd a beépített **Issue tracckert**
+    * A **commitok** megjegyzés hozzáfűzési lehetőségét
+    * Továbbá az alább leírt szerkesztési szabályokat és a Merge request-ek rendszerét, az azokban végezhető kommentelési lehetőségeket
+    * A kommunikációban preferáld az említések, és hivatkozások használatát
+* A project open, hogy a dokumentáció a közvetlen gitlab.vonalkod.hu alatti linkkel egyszerűen meg lehessen osztani **bárkivel**.
+* Mivel a fő megjelenítőnk a gitlab, ezért *GitLab Flavored Markdown*-t használunk. A cél, hogy a gitlab [kiszólgálónkon][#ourgitlab] jól nézzen ki. GFM-ről dokumentáció [itt][#gitlabmddoc]
+* Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster]
+* Vagy egyszerűen használd a gitlab beépített markdown editorát... 
+* Minden egyes MD fájl külön verziózást kap, amit a fájl első sorában kell feltüntetni (pl.: v1.2.3).
+    * A verziózás [Semantic Versioning][#semver] szerint történik az alábbi egyértelműsítések figyelembe vételével:
+        * API: A dokumentáció szemantikai (jelentés)tartalma
+        * Patch: Csak szerkesztési (editorial) kategóriájú változtatások (lásd: contribution.md)
+        * Minor (compatibility API change): Kizárólag olyan szemantikai változtatások, melyek nem tartalmaznak ellentétes állításokat az előző verzió állításaival, és nem hagynak el elemeket belőle (tehát bővítik a szemantikát és nem megváltoztatják a létezőt, vagy szűkítik azt)
+        * Major (incompatibility API change): Olyan szemantikai változtatások, melyek megváltoztatják az előző verzió állításait, vagy elhagynak abból elemeket.
+
+> # **Follow the rules!**
+
+[#headerpic]: <http://web.vonalkod.hu/fejlesztes/devprocdoc/rules.png>
+[#webvonalkodhuftp]:<http://redmine.vonalkod.hu/projects/vrhfejlesztes/wiki/Bels%C5%91_h%C3%A1l%C3%B3zat#VRH-infrastrukt%C3%BAra-WebSzolg%C3%A1ltat%C3%A1sok-elr%C3%A9%C3%A9sei>
+[#ourgitlab]:<http://gitlab.vonalkod.hu:443/vrh/devprocdoc>
+[#gitlabmddoc]: <https://gitlab.com/help/user/markdown>
+[#markdownmonster]: <https://markdownmonster.west-wind.com/download.aspx>
+[#semver]: <https://semver.org>
 \ No newline at end of file
@@ -0,0 +1,17 @@
+#https://www.websequencediagrams.com/
+develop->rfc_my-first-rfc: Start RFC (create branch)
+rfc_my-first-rfc->rfc_my-first-rfc: Work on change/create 
+rfc_my-first-rfc->contribution_another-edit-in-this-rfc: Start contribution (create branch)
+contribution_another-edit-in-this-rfc->contribution_another-edit-in-this-rfc: Work on change
+contribution_another-edit-in-this-rfc->rfc_my-first-rfc: Publication: create MR assign to original RFC's owner
+rfc_my-first-rfc->contribution_another-edit-in-this-rfc: Accept/Refuse (delete contribution branch)
+destroy contribution_another-edit-in-this-rfc
+rfc_my-first-rfc->develop: Publication: create MR assign to dev-leader
+develop->rfc_my-first-rfc: Accept/Refuse (delete rfc branch)
+destroy rfc_my-first-rfc
+develop->editorial_my-first-editorial-contribution: Start editorial change (create branch)
+editorial_my-first-editorial-contribution->editorial_my-first-editorial-contribution: Work on change
+editorial_my-first-editorial-contribution->develop: Publication: create MR assign to itself or dev-head
+develop->editorial_my-first-editorial-contribution: Accept/refuse (delete editorial branch)
+destroy editorial_my-first-editorial-contribution
+develop->master: Publication (MR into master branch by dev-leader only)
@@ -0,0 +1,47 @@
+**v1.0.0** 
+
+*#mainteiner:* @zgorcsos
+# Együttműködési szabályok
+1. A *develop* branchet **nem** használjuk szerkesztésre! 
+2. **Bármilyen** változtatáshoz a __develop__ brench-ből egy feauture branch-et kell származtatni. 
+    * Ezen branchek elnevezése **szigorúan kötött**! Jelenleg az alábbi három prefix közül kell **kötelezően** az egyiket alkalmazni:
+        1. **editorial_**: Ilyen címkével ellátott branch-en, kizárólag olyan módosítás végezhető egy létező dokumentumon, amely szerkesztési jellegű változtatást jelent. Nagyon fontos, hogy ilyen branch-en nem végezhető el **semmilyen** olyan jellegű módosítás, amelyik a dokumentáció szemantikai tartalmán érdemben változtat! 
+            * editorial_ branch-en végezhető módosítások: 
+                - Helyesírási hibák, elírások javítása
+                - Rossz nyelvi konstrukciók egyértelműsítése, javítása
+                - Szerencsétlen, nem sikerült megfogalmazások kiigazítása
+            * editorial_ branch lezárása:
+                - A szerkesztés lezárása, és a szerkesztési módosítás javaslattétele egy a develop branchre létrehozott MR (merge request segítségével történik).
+                - Ezen MR célszemélye ("Assign to") a dokumentációban feltüntetett dokumentum legelején "#mainteiner:" címkével feltüntetett felelős, ha nincs ilyen feltüntetve, akkor a fejlesztési vezető
+                - editorial_ brancról való olvasztást kizárólag az MR célszemélye, vagy a fejlesztési vezető végezheti el!
+        2. **rfc_**: Minden érdemi tartalmi módosításnak, új dokumentáció létrehozásának egy rfc_ prefixxel ellátott branch-en kell történnie, függetlenül attól, hogy az adott módosítást ki kívánja végrehajtani a dokumentáción! Ez alól a dokumentum felelőse, és a fejlesztési vezető sem kivétel! (*Az RFC a Request For Comments rövidítése és általánosan elterjedt elnevezés együttműködés alapú dokumentációk előállításakor. Az RFC arra hívja fel a közösséget, hogy alakítsanak ki közös konszenzusos álláspontot az adott kérdésben, és a lépésben létrehozott eredmény ezt tükrözze. Ez természetesen lehet a kérés elutasítása is.*)
+            * Szabályok az rfc_ branchen:
+                - Egy rfc_-ben elvégzett módosítás mindig egy a develop brancre létreozott MR (merge request) formájában kerül publikálásra
+                - Egy rfc_-nek egyértelműen egy tulajdonosa van (editor) nem indítunk konkurens commitot egy rfc-re.
+                - Ehelyett az érdemi szerkesztést megvalósító együttműködés az rfc-ből származtatott contribution_ prefixxel ellátott branch-en történik, és az eredeti rfc_ branchre létrehozott MR (merge request) formájában ölt testet. Részletesen lásd a contribution_ prefix leírásánál!
+                - Az rfc_ branchekből létrehozott MR-ek „célzása”: 
+                        
+                        - Csakis a develop branch-re irányulhat
+                        - Az MR célszemélye ("assign to") minden esetben a fejlesztési vezető, a Merge kizárólag általa végezhető el!
+                - Megengedett ugyanakkor, hogy egy dokumentumra párhuzamosan több rfc_ fusson. (Értelemszerűen ezek nem vonatkoznak ugyanazon részekre, mielőtt rfc-t nyitsz, mindig nézd meg, nincs-e már folyamatban egy az adott témára (dokumentum részre)! Ezért fontosak az érthető, beszédes branch elnevezések!) 
+        3. **contribution_**: Ha egy futó rfc_-re a commenteken (legyen az egy nyitott issue, commit, vagy MR comment) túlmutató javaslat szükséges, akkor az alábbiak szerint kell eljárni: 
+            * rfc_ brancből egy contribution_ prefixxel ellátott branch-et kell származtatni
+            * A módosításokat itt megejteni, majd egy az eredeti rfc_ brancre irányuló MR (merge request) formájában publikálni. Szabályok:
+                * A szerkesztési szándékot egyeztetni kell a kommunikáció során!
+                * Az MR célszemélye az rfc eredeti tulajdonosa. A merge-et ő vagy a fejlesztési vezető végezheti el!
+    * **Branchek elnevezése:** 
+        * A prefixek jobb láthatósága érdekében ne használjuk a branchek elnevezésében a "_" jelet az elnevezés tagolására. 
+        * Javasolt helyette a kötőjelek alkalmazása. CamelCase írásmód is megengedett. 
+        * Tagolás nélküli elnevezések használata kerülendő! 
+        * Ne használjunk rövidítéseket, hacsak azok nem vitán felül közismert és egyértelmű jelölések a szakmai nyelvben!
+3. A **develeop** branchen lévő dokumentációk is csak "strawman"-nak tekintendőek! 
+4. Ha egy dokumentáció végleges változatként elkészül, akkor a fejlesztési vezető MR-t készít és végez a master branchre.
+5. Hogy a félkész dokumentációk ne blokkolják más dokumentációk publikálását, ezért minden rfc_-t addig tartunk meg, amíg a strawman állapota publikálásra kész változatot nem ér el. A merge a develop brancre csak ezután történik, amelyet általában azonnali „develop to master” merge követ.
+6. A fueture brancheket az elvégzett merge-eket követően töröljük.
+7. A nyilvánossá tett dokumentáció hivatkozások mindig a master brancre irányulnak (gitlab linkek)
+
+A branching modell vizuálisan szemléltetve:
+
+![][#contribution-branching-model]
+
+[#contribution-branching-model]:<http://web.vonalkod.hu/fejlesztes/devprocdoc/contribution-branching-model.PNG>
 \ No newline at end of file