Hogyan járuljunk hozzá a kódhoz

Készülsz hozzájárulni a Nette Frameworkhöz, és szükséged van eligazodásra a szabályokban és eljárásokban? Ez a kezdőknek szóló útmutató lépésről lépésre megmutatja, hogyan járulhatsz hozzá hatékonyan a kódhoz, hogyan dolgozz a repository-kkal és hogyan implementáld a változtatásokat.

Eljárás

A kódhoz való hozzájáruláshoz elengedhetetlen egy GitHub fiók és a Git verziókezelő rendszer alapjainak ismerete. Ha nem ismered a Git használatát, megnézheted a git – the simple guide útmutatót, és esetleg használhatod a számos grafikus kliens egyikét.

Környezet és repository előkészítése

  1. a GitHubon hozz létre egy forkot annak a csomagnak a repository-jából, amelyet módosítani készülsz
  2. ezt a repository-t klónozd a számítógépedre
  3. telepítsd a függőségeket, beleértve a Nette Testert is, a composer install paranccsal
  4. ellenőrizd, hogy a tesztek működnek-e, a composer tester futtatásával
  5. hozz létre egy új ágat az utolsó kiadott verzió alapján

Saját változtatások implementálása

Most végrehajthatod a saját kódmódosításaidat:

  1. programozd le a kívánt változtatásokat, és ne feledkezz meg a tesztekről
  2. győződj meg róla, hogy a tesztek sikeresen lefutnak, a composer tester segítségével
  3. ellenőrizd, hogy a kód megfelel-e a kódolási szabványnak
  4. mentsd el a változtatásokat (commitold) egy leírással ebben a formátumban

Létrehozhatsz több commitot, egyet minden logikai lépéshez. Minden commitnak önmagában értelmesnek kell lennie.

Változtatások elküldése

Amint elégedett vagy a változtatásokkal, elküldheted őket:

  1. küldd el (pushold) a változtatásokat a GitHubra a saját forkodba
  2. onnan küldd el őket a Nette repository-ba egy pull request (PR) létrehozásával
  3. adj meg a leírásban elegendő információt

Észrevételek beépítése

A commitjaidat most már mások is látni fogják. Gyakori, hogy észrevételeket tartalmazó kommenteket kapsz:

  1. kövesd nyomon a javasolt módosításokat
  2. építsd be őket új commitokként, vagy olvaszd össze őket a korábbiakkal
  3. küldd el újra a commitokat a GitHubra, és automatikusan megjelennek a pull requestben

Soha ne hozz létre új pull requestet egy meglévő módosítása miatt.

Dokumentáció

Ha megváltoztattad a funkcionalitást vagy újat adtál hozzá, ne felejtsd el hozzáadni a dokumentációhoz is.

Új ág

Ha lehetséges, a változtatásokat az utolsó kiadott verzióhoz képest végezd, azaz az adott ág utolsó tagjéhez. A v3.2.1 taghez ezzel a paranccsal hozhatsz létre ágat:

git checkout -b new_branch_name v3.2.1

Kódolási szabványok

A kódodnak meg kell felelnie a Nette Frameworkben használt kódolási szabványnak. A kód ellenőrzésére és javítására rendelkezésre áll egy automatikus eszköz. Telepíthető a Composer segítségével globálisan egy általad választott mappába:

composer create-project nette/coding-standard /path/to/nette-coding-standard

Most már képesnek kell lenned futtatni az eszközt a terminálban. Az első parancs ellenőrzi, a második pedig javítja is a kódot az src és tests mappákban az aktuális könyvtárban:

/path/to/nette-coding-standard/ecs check
/path/to/nette-coding-standard/ecs check --fix

Commit leírása

A Nette-ben a commit tárgyak formátuma: Presenter: fixed AJAX detection [Closes #69]

  • terület, amelyet kettőspont követ
  • a commit célja múlt időben, ha lehetséges, kezdődjön a következő szavakkal: added (új funkció hozzáadva), fixed (javítás), refactored (kódváltozás viselkedésváltozás nélkül), changed, removed
  • ha a commit megszakítja a visszamenőleges kompatibilitást, add hozzá a “BC break” jelzést
  • esetleges kapcsolat az issue trackerrel, mint (#123) vagy [Closes #69]
  • a tárgy után következhet egy üres sor, majd részletesebb leírás, beleértve például a fórumra mutató linkeket

Pull request leírása

Pull request létrehozásakor a GitHub felülete lehetővé teszi egy név és leírás megadását. Adj meg egy kifejező nevet, és a leírásban adj meg minél több információt a változtatásod okairól.

Megjelenik egy fejléc is, ahol meg kell adnod, hogy új funkcióról vagy hibajavításról van-e szó, és hogy okozhat-e visszamenőleges kompatibilitási törést (BC break). Ha van kapcsolódó probléma (issue), hivatkozz rá, hogy a pull request jóváhagyása után lezárásra kerüljön.

- bug fix / new feature?  <!-- #issue számok, ha vannak -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- nagyon szívesen látjuk, lásd https://nette.org/en/writing -->
  1. Dokumentáció
  2. Legyen Ön is Nette hozzájáruló
  3. Hogyan járuljunk hozzá a kódhoz