VRH / devprocdoc

Commit a896adde5121b653caa26141899f914dc03a9272

Authored by Görcsös Zoltán
1 parent 84318e82

Update readme.md

Showing 1 changed file with 48 additions and 2 deletions   Show diff stats
Inline Side-by-side
README.md
  Show/Hide comments   View file @a896add
  1 +*#mainteiner:* @zgorcsos
  2 +
1 3 ![][#headerpic]
2 4  
3 5 # devprocdoc = Developer Process Documentation
... ... @@ -7,16 +9,60 @@
7 9 * A dokumentáció **kizárólag** markdown alapú!
8 10 * A dokumentáció organizációja **könyvtárakra** törve történik
9 11 * A repository az MD fájlokon túl képeket tartalmazhat, melyek a markdown fájlokban hivatkozásra kerülnek.
10   -* A diskurzus a dokumentáció tartalmáról **kizárólag** itt történik!
  12 +* A diskurzus a dokumentációk tartalmáról **kizárólag** itt történik!
11 13 * Használd a beépített **Issue tracckert**
12   - * és a **commitok** megjegyzés hozzáfűzési lehetőségét
  14 + * A **commitok** megjegyzés hozzáfűzési lehetőségét
  15 + * 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
  16 + * A kommunikációban preferáld az említések, és hívatkozások használatát
13 17 * A project open, hogy a dokumentáció a közvetlen gitlab.vonalkod.hu alatti linkkel egyszerűen meg lehessen osztani **bárkivel**.
14 18 * Mivel a fő megjelenítőnk a gitlab, ezért *GitLab Flavored Markdown*-t használunk. A cél, hogy a gitlabon jól nézzen ki. GFM-ről dokumentáció [itt][#gitlabmddoc]
15 19 * Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster]
16 20 * Vagy egyszerűen használd a gitlab beépített markdown editorát...
17 21  
  22 +### Dokumentum változtatási szabályok:
  23 +1. A *develop* branchet **nem** használjuk szerkesztésre!
  24 +2. Bármilyen változtatáshoz a __develop__ brenchből egy feauture branch-et kell származtatni.
  25 + * Ezen branchek elnevezése kötött! Jelenleg az alábbi három prefix közül kell **kötelezően** az egyiket alkalmazni:
  26 + 1. **editorial_**: Ilyen cimkével elá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 branchen nem végezhető el **semmilyen** olyan jellegű módósítás, amelyik a dokumentáció szemantikai tartalmán érdemben változtat!
  27 + * editorial_ branchen végezhető módosítások:
  28 + - Helyesírási hibák, elírások javítása
  29 + - Rossz nyelvi konstrukciók egyélrtelműsítése, javítása
  30 + - Szerencsétlen, nem sikerült megfogalamazások kiigazítása
  31 + * editorial_ branch lezárása:
  32 + - 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).
  33 + - 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ő
  34 + - editorial_ brancról való olvasztást kizárólag az MR célszemélye, vagy a fejlesztési vezető végezheti el!
  35 + 2. **rfc_**: Minden érdemi tratlami módosításnak, új dokumentáció létrehozáésának egy rfc_ prefixxel elátott branchen kell történnie, függetlenül attól, hogy az adott módosítást ki kivá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ütmüködés alapú dokumentációk előállításakor.*)
  36 + * Szabályok az rfc_ branchen:
  37 + - Egy rfc_-ben elvégzett módosítás mindig egy a develop brancre létreozott MR (mereg request) formájában kerül publikálásra
  38 + - Egy rfc_-nek egyértelműen egy tulajdonosa van (editor) nem indítunk konkurens commitot egy rfc-re.
  39 + - Ehelyett a szerkesztési együtműködés az rfc-ből származtatott contribution_ prefixxel elátott branchen történik, és az eredeti rfc_ branchre létrehozott MR (merge request) formájában valósul meg. Részletesen lásd a contribution_ prefix leírásánál!
  40 + - Az rfc_ branchekből létrehozott MR-ek célzása:
  41 +
  42 + - Csakis a develop branch-re irányulhat
  43 + - Az MR célszemélye ("assign to") minden esetben a fejlesztési vezető, a Merge kizárólag általa végezhető el!
  44 + - 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ézde meg, nincs-e már folyamatban egy rá! Ezért fontosak az érthető, beszédes branch elnevezések!)
  45 + 3. **contribution_**: Ha egy futó rfc_-re a commenteken (legyen az egy nyitott issue, commit comment, vagy MR comment) túlmutató javaslat szükséges, akkor az alábbiak szerint kell eljárni:
  46 + * rfc_ brancből egy contribution_ prefixxel elátott branchet kell származtatni
  47 + * A módosításokat itt megejteni, majd majd egy az eredeti rfc_ brancre irányuló MR (merge request) formájában publikálni. Szabályok:
  48 + * A szerkesztési szándékot egyeztetni kell!
  49 + * Az MR célszemélye az rfc eredeti tulajdonosa. A merge-et ő vagy a fejhlesztési vezető végezheti el!
  50 + * **Branchek elnevezése:**
  51 + * 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.
  52 + * Javasolt helyette a kötöjelek alklamazása. Camel Case írásmód is megengedett.
  53 + * Tagolás nélküli elnevezések használata kerülendő!
  54 + * 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!
  55 +3. A **develeop** branchen lévő dokumentációk is csak "strawman"-nak tekintendőek!
  56 +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.
  57 +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 azonali develop to master merge követ.
  58 +6. A fueture brancheket az elvégzett merge-eket követően töröljük.
  59 +
  60 +A branch modell vizuálisan szemléltetve:
  61 +
  62 +
18 63 > # **Follow the rules!**
19 64  
20 65 [#headerpic]: <http://gitlab.vonalkod.hu:443/uploads/project/avatar/193/rules.png>
21 66 [#gitlabmddoc]: <https://gitlab.com/help/user/markdown>
22 67 [#markdownmonster]: <https://markdownmonster.west-wind.com/download.aspx>
  68 +[#branchmodel-illustration]: <http://gitlab.vonalkod.hu:443/>
23 69 \ No newline at end of file
... ...