#mainteiner: @zgorcsos

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
• A repository az MD fájlokon túl képeket tartalmazhat, melyek a markdown fájlokban hivatkozásra kerülnek.
• 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 hívatkozá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 gitlabon jól nézzen ki. GFM-ről dokumentáció itt
• Jó offline MD szerkesztő: Markdown Monster
• Vagy egyszerűen használd a gitlab beépített markdown editorát...

Dokumentum változtatási szabályok:

1. A develop branchet nem használjuk szerkesztésre!

2. Bármilyen változtatáshoz a develop brenchből egy feauture branch-et kell származtatni.

   • Ezen branchek elnevezése kötött! Jelenleg az alábbi három prefix közül kell kötelezően az egyiket alkalmazni:

     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!
        • editorial_ branchen végezhető módosítások:
          • Helyesírási hibák, elírások javítása
          • Rossz nyelvi konstrukciók egyélrtelműsítése, javítása
          • Szerencsétlen, nem sikerült megfogalamazá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 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.)

        • Szabályok az rfc_ branchen:

          • 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
          • Egy rfc_-nek egyértelműen egy tulajdonosa van (editor) nem indítunk konkurens commitot egy rfc-re.
          • 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!

          • 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ézde meg, nincs-e már folyamatban egy rá! 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 comment, vagy MR comment) túlmutató javaslat szükséges, akkor az alábbiak szerint kell eljárni:

        • rfc_ brancből egy contribution_ prefixxel elátott branchet kell származtatni
        • 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:
          • A szerkesztési szándékot egyeztetni kell!
          • Az MR célszemélye az rfc eredeti tulajdonosa. A merge-et ő vagy a fejhleszté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 alklamazása. Camel Case í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 azonali develop to master merge követ.

6. A fueture brancheket az elvégzett merge-eket követően töröljük.

7. Dokumentáció hivatkozások mindig a master brancre irányulnak

A branch modell vizuálisan szemléltetve:

Follow the rules!