From a896adde5121b653caa26141899f914dc03a9272 Mon Sep 17 00:00:00 2001 From: Görcsös Zoltán Date: Tue, 4 Dec 2018 11:41:44 +0100 Subject: [PATCH] Update readme.md --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 48 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 353b140..6d275ae 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,5 @@ +*#mainteiner:* @zgorcsos + ![][#headerpic] # devprocdoc = Developer Process Documentation @@ -7,16 +9,60 @@ * 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ó tartalmáról **kizárólag** itt történik! +* A diskurzus a dokumentációk tartalmáról **kizárólag** itt történik! * Használd a beépített **Issue tracckert** - * és a **commitok** megjegyzés hozzáfűzési lehetőségét + * 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][#gitlabmddoc] * Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster] * 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. + +A branch modell vizuálisan szemléltetve: + + > # **Follow the rules!** [#headerpic]: [#gitlabmddoc]: [#markdownmonster]: +[#branchmodel-illustration]: \ No newline at end of file -- libgit2 0.21.2