Как да допринесете към кода

Подготвяте се да допринесете към Nette Framework и трябва да се ориентирате в правилата и процедурите? Този наръчник за начинаещи ще ви покаже стъпка по стъпка как ефективно да допринасяте към кода, да работите с хранилища и да внедрявате промени.

Процедура

За да допринесете към кода, е необходимо да имате акаунт в GitHub и да сте запознати с основите на работа със системата за контрол на версиите Git. Ако не владеете работата с Git, можете да разгледате ръководството git – the simple guide и евентуално да използвате някой от многото графични клиенти.

Подготовка на средата и хранилището

  1. В GitHub си създайте fork на хранилището на пакета, който се готвите да промените
  2. Клонирайте това хранилище на своя компютър
  3. Инсталирайте зависимостите, включително Nette Tester, с командата composer install
  4. Проверете дали тестовете работят, като стартирате composer tester
  5. Създайте си нов branch базиран на последната издадена версия

Внедряване на собствени промени

Сега можете да направите своите собствени промени в кода:

  1. програмирайте желаните промени и не забравяйте тестовете
  2. уверете се, че тестовете преминават успешно, с помощта на composer tester
  3. проверете дали кодът отговаря на стандарта за кодиране
  4. запазете промените (commit) с описание в този формат

Можете да създадете няколко commit-а, по един за всяка логическа стъпка. Всеки commit трябва да бъде смислен сам по себе си.

Изпращане на промените

След като сте доволни от промените, можете да ги изпратите:

  1. изпратете (push) промените в GitHub към вашия fork
  2. оттам ги изпратете към Nette хранилището, като създадете pull request (PR)
  3. посочете в описанието достатъчно информация

Обработване на забележките

Вашите commit-и сега ще бъдат видени и от други. Обичайно е да получите коментари със забележки:

  1. следете предложените корекции
  2. обработете ги като нови commit-и или ги обединете с предишните
  3. отново изпратете commit-ите в GitHub и те автоматично ще се появят в pull request-а

Никога не създавайте нов pull request за корекция на съществуващ.

Документация

Ако сте променили функционалност или сте добавили нова, не забравяйте да я добавите и в документацията.

Нов branch

Ако е възможно, правете промените спрямо последната издадена версия, т.е. последния таг в дадения branch. За таг v3.2.1 ще създадете branch с тази команда:

git checkout -b new_branch_name v3.2.1

Стандарти за кодиране

Вашият код трябва да отговаря на стандарта за кодиране, използван в Nette Framework. За проверка и корекция на кода е наличен автоматичен инструмент. Може да бъде инсталиран чрез Composer глобално във ваша избрана папка:

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

Сега трябва да можете да стартирате инструмента в терминала. С първата команда ще проверите, а с втората и ще коригирате кода в папките src и tests в текущата директория:

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

Описание на commit

В Nette темите на commit-ите имат формат: Presenter: fixed AJAX detection [Closes #69]

  • област, последвана от двоеточие
  • целта на commit-а в минало време; ако е възможно, започнете с думата: “added” (добавена нова функционалност), “fixed” (корекция), “refactored” (промяна в кода без промяна на поведението), “changed”, “removed”
  • ако commit-ът нарушава обратната съвместимост, добавете “BC break”
  • евентуална връзка към issue tracker като (#123) или [Closes #69]
  • след темата може да последва един празен ред и след това по-подробно описание, включително например връзки към форума

Описание на pull request

При създаване на pull request интерфейсът на GitHub ще ви позволи да въведете заглавие и описание. Посочете описателно заглавие и в описанието предоставете колкото се може повече информация за причините за вашата промяна.

Ще се покаже и заглавие, където да посочите дали става въпрос за нова функция или корекция на грешка и дали може да настъпи нарушаване на обратната съвместимост (BC break). Ако има свързан проблем (issue), посочете го, за да бъде затворен след одобрение на pull request-а.

- bug fix / new feature?  <!-- #issue номера, ако има -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- силно приветствано, вижте https://nette.org/en/writing -->
  1. Документация
  2. Станете сътрудник на Nette
  3. Как да допринесете към кода