Commit a896adde5121b653caa26141899f914dc03a9272
1 parent
84318e82
Update readme.md
Showing
1 changed file
with
48 additions
and
2 deletions
Show diff stats
README.md
| 1 | +*#mainteiner:* @zgorcsos | ||
| 2 | + | ||
| 1 | ![][#headerpic] | 3 | ![][#headerpic] |
| 2 | 4 | ||
| 3 | # devprocdoc = Developer Process Documentation | 5 | # devprocdoc = Developer Process Documentation |
| @@ -7,16 +9,60 @@ | @@ -7,16 +9,60 @@ | ||
| 7 | * A dokumentáció **kizárólag** markdown alapú! | 9 | * A dokumentáció **kizárólag** markdown alapú! |
| 8 | * A dokumentáció organizációja **könyvtárakra** törve történik | 10 | * A dokumentáció organizációja **könyvtárakra** törve történik |
| 9 | * A repository az MD fájlokon túl képeket tartalmazhat, melyek a markdown fájlokban hivatkozásra kerülnek. | 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 | * Használd a beépített **Issue tracckert** | 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 | * A project open, hogy a dokumentáció a közvetlen gitlab.vonalkod.hu alatti linkkel egyszerűen meg lehessen osztani **bárkivel**. | 17 | * A project open, hogy a dokumentáció a közvetlen gitlab.vonalkod.hu alatti linkkel egyszerűen meg lehessen osztani **bárkivel**. |
| 14 | * 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] | 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 | * Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster] | 19 | * Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster] |
| 16 | * Vagy egyszerűen használd a gitlab beépített markdown editorát... | 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 | > # **Follow the rules!** | 63 | > # **Follow the rules!** |
| 19 | 64 | ||
| 20 | [#headerpic]: <http://gitlab.vonalkod.hu:443/uploads/project/avatar/193/rules.png> | 65 | [#headerpic]: <http://gitlab.vonalkod.hu:443/uploads/project/avatar/193/rules.png> |
| 21 | [#gitlabmddoc]: <https://gitlab.com/help/user/markdown> | 66 | [#gitlabmddoc]: <https://gitlab.com/help/user/markdown> |
| 22 | [#markdownmonster]: <https://markdownmonster.west-wind.com/download.aspx> | 67 | [#markdownmonster]: <https://markdownmonster.west-wind.com/download.aspx> |
| 68 | +[#branchmodel-illustration]: <http://gitlab.vonalkod.hu:443/> | ||
| 23 | \ No newline at end of file | 69 | \ No newline at end of file |