Commit a9903bc82329d3011e49f140aff31bb373757b2d
Merge branch 'rfc_devprocdoc-rules-strawman' into 'develop'
Rfc devprocdoc rules strawman @vvadasz @jjuras @pthiering Spektáljátok meg ezt a két MD fájlt. Ez szabályozná, hogyan történne a fejlesztési dokumentációk fejlesztése, és az ezzel kapcsolatos kommunikáció. See merge request !1
Showing
5 changed files
with
85 additions
and
5 deletions
Show diff stats
README.md
| 1 | +**v1.0.0** | ||
| 2 | + | ||
| 3 | +*#mainteiner:* @zgorcsos | ||
| 4 | + | ||
| 1 | ![][#headerpic] | 5 | ![][#headerpic] |
| 2 | 6 | ||
| 3 | # devprocdoc = Developer Process Documentation | 7 | # devprocdoc = Developer Process Documentation |
| @@ -6,17 +10,29 @@ | @@ -6,17 +10,29 @@ | ||
| 6 | ## Szabályok: | 10 | ## Szabályok: |
| 7 | * A dokumentáció **kizárólag** markdown alapú! | 11 | * A dokumentáció **kizárólag** markdown alapú! |
| 8 | * A dokumentáció organizációja **könyvtárakra** törve történik | 12 | * 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. | ||
| 10 | -* A diskurzus a dokumentáció tartalmáról **kizárólag** itt történik! | 13 | +* 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! |
| 14 | +* A fenti feltöltött, és az md fájlokban hivatkozott képeket a repository-hoz is hozzáadjuk! | ||
| 15 | +* 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** | 16 | * Használd a beépített **Issue tracckert** |
| 12 | - * és a **commitok** megjegyzés hozzáfűzési lehetőségét | 17 | + * A **commitok** megjegyzés hozzáfűzési lehetőségét |
| 18 | + * 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 | ||
| 19 | + * A kommunikációban preferáld az említések, és hivatkozá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**. | 20 | * 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] | 21 | +* 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] |
| 15 | * Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster] | 22 | * Jó offline MD szerkesztő: [Markdown Monster][#markdownmonster] |
| 16 | * Vagy egyszerűen használd a gitlab beépített markdown editorát... | 23 | * Vagy egyszerűen használd a gitlab beépített markdown editorát... |
| 24 | +* 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). | ||
| 25 | + * A verziózás [Semantic Versioning][#semver] szerint történik az alábbi egyértelműsítések figyelembe vételével: | ||
| 26 | + * API: A dokumentáció szemantikai (jelentés)tartalma | ||
| 27 | + * Patch: Csak szerkesztési (editorial) kategóriájú változtatások (lásd: contribution.md) | ||
| 28 | + * 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) | ||
| 29 | + * 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. | ||
| 17 | 30 | ||
| 18 | > # **Follow the rules!** | 31 | > # **Follow the rules!** |
| 19 | 32 | ||
| 20 | -[#headerpic]: <http://gitlab.vonalkod.hu:443/uploads/project/avatar/193/rules.png> | 33 | +[#headerpic]: <http://web.vonalkod.hu/fejlesztes/devprocdoc/rules.png> |
| 34 | +[#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> | ||
| 35 | +[#ourgitlab]:<http://gitlab.vonalkod.hu:443/vrh/devprocdoc> | ||
| 21 | [#gitlabmddoc]: <https://gitlab.com/help/user/markdown> | 36 | [#gitlabmddoc]: <https://gitlab.com/help/user/markdown> |
| 22 | [#markdownmonster]: <https://markdownmonster.west-wind.com/download.aspx> | 37 | [#markdownmonster]: <https://markdownmonster.west-wind.com/download.aspx> |
| 38 | +[#semver]: <https://semver.org> | ||
| 23 | \ No newline at end of file | 39 | \ No newline at end of file |
69.6 KB
| @@ -0,0 +1,17 @@ | @@ -0,0 +1,17 @@ | ||
| 1 | +#https://www.websequencediagrams.com/ | ||
| 2 | +develop->rfc_my-first-rfc: Start RFC (create branch) | ||
| 3 | +rfc_my-first-rfc->rfc_my-first-rfc: Work on change/create | ||
| 4 | +rfc_my-first-rfc->contribution_another-edit-in-this-rfc: Start contribution (create branch) | ||
| 5 | +contribution_another-edit-in-this-rfc->contribution_another-edit-in-this-rfc: Work on change | ||
| 6 | +contribution_another-edit-in-this-rfc->rfc_my-first-rfc: Publication: create MR assign to original RFC's owner | ||
| 7 | +rfc_my-first-rfc->contribution_another-edit-in-this-rfc: Accept/Refuse (delete contribution branch) | ||
| 8 | +destroy contribution_another-edit-in-this-rfc | ||
| 9 | +rfc_my-first-rfc->develop: Publication: create MR assign to dev-leader | ||
| 10 | +develop->rfc_my-first-rfc: Accept/Refuse (delete rfc branch) | ||
| 11 | +destroy rfc_my-first-rfc | ||
| 12 | +develop->editorial_my-first-editorial-contribution: Start editorial change (create branch) | ||
| 13 | +editorial_my-first-editorial-contribution->editorial_my-first-editorial-contribution: Work on change | ||
| 14 | +editorial_my-first-editorial-contribution->develop: Publication: create MR assign to itself or dev-head | ||
| 15 | +develop->editorial_my-first-editorial-contribution: Accept/refuse (delete editorial branch) | ||
| 16 | +destroy editorial_my-first-editorial-contribution | ||
| 17 | +develop->master: Publication (MR into master branch by dev-leader only) |
| @@ -0,0 +1,47 @@ | @@ -0,0 +1,47 @@ | ||
| 1 | +**v1.0.0** | ||
| 2 | + | ||
| 3 | +*#mainteiner:* @zgorcsos | ||
| 4 | +# Együttműködési szabályok | ||
| 5 | +1. A *develop* branchet **nem** használjuk szerkesztésre! | ||
| 6 | +2. **Bármilyen** változtatáshoz a __develop__ brench-ből egy feauture branch-et kell származtatni. | ||
| 7 | + * 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: | ||
| 8 | + 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! | ||
| 9 | + * editorial_ branch-en végezhető módosítások: | ||
| 10 | + - Helyesírási hibák, elírások javítása | ||
| 11 | + - Rossz nyelvi konstrukciók egyértelműsítése, javítása | ||
| 12 | + - Szerencsétlen, nem sikerült megfogalmazások kiigazítása | ||
| 13 | + * editorial_ branch lezárása: | ||
| 14 | + - 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). | ||
| 15 | + - 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ő | ||
| 16 | + - editorial_ brancról való olvasztást kizárólag az MR célszemélye, vagy a fejlesztési vezető végezheti el! | ||
| 17 | + 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.*) | ||
| 18 | + * Szabályok az rfc_ branchen: | ||
| 19 | + - 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 | ||
| 20 | + - Egy rfc_-nek egyértelműen egy tulajdonosa van (editor) nem indítunk konkurens commitot egy rfc-re. | ||
| 21 | + - 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! | ||
| 22 | + - Az rfc_ branchekből létrehozott MR-ek „célzása”: | ||
| 23 | + | ||
| 24 | + - Csakis a develop branch-re irányulhat | ||
| 25 | + - Az MR célszemélye ("assign to") minden esetben a fejlesztési vezető, a Merge kizárólag általa végezhető el! | ||
| 26 | + - 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!) | ||
| 27 | + 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: | ||
| 28 | + * rfc_ brancből egy contribution_ prefixxel ellátott branch-et kell származtatni | ||
| 29 | + * 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: | ||
| 30 | + * A szerkesztési szándékot egyeztetni kell a kommunikáció során! | ||
| 31 | + * Az MR célszemélye az rfc eredeti tulajdonosa. A merge-et ő vagy a fejlesztési vezető végezheti el! | ||
| 32 | + * **Branchek elnevezése:** | ||
| 33 | + * 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. | ||
| 34 | + * Javasolt helyette a kötőjelek alkalmazása. CamelCase írásmód is megengedett. | ||
| 35 | + * Tagolás nélküli elnevezések használata kerülendő! | ||
| 36 | + * 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! | ||
| 37 | +3. A **develeop** branchen lévő dokumentációk is csak "strawman"-nak tekintendőek! | ||
| 38 | +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. | ||
| 39 | +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. | ||
| 40 | +6. A fueture brancheket az elvégzett merge-eket követően töröljük. | ||
| 41 | +7. A nyilvánossá tett dokumentáció hivatkozások mindig a master brancre irányulnak (gitlab linkek) | ||
| 42 | + | ||
| 43 | +A branching modell vizuálisan szemléltetve: | ||
| 44 | + | ||
| 45 | +![][#contribution-branching-model] | ||
| 46 | + | ||
| 47 | +[#contribution-branching-model]:<http://web.vonalkod.hu/fejlesztes/devprocdoc/contribution-branching-model.PNG> | ||
| 0 | \ No newline at end of file | 48 | \ No newline at end of file |
59.1 KB