Принос към кода

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

Процедура

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

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

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

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

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

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

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

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

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

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

Включване на обратна връзка

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

  1. Следете предложените промени
  2. Включете ги като нови коммити или ги слейте с предишните
  3. Изпратете отново коммитите в GitHub и те автоматично ще се появят в заявката за изтегляне

Никога не създавайте нова заявка за изтегляне, за да промените съществуваща.

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

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

Нов клон

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

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

Ангажимент Описание

В Nette темите на ангажиментите имат следния формат: Presenter: fixed AJAX detection [Closes #69]

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

Описание на заявката за изтегляне

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

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

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