Предлагане на промяна в кодекса

Nette Framework използва Git и GitHub за поддържане на базата с код. Най-добрият начин да дадете своя принос е да запишете промените си в собственото си разклонение и след това да направите заявка за изтегляне в GitHub. В този документ са обобщени основните стъпки за успешно допринасяне.

Подготовка на средата

Започнете с разклоняване на Nette в GitHub. Внимателно настройте локалната си среда на Git, конфигурирайте потребителското си име и имейл, тези данни ще идентифицират промените ви в историята на Nette Framework.

Работа по вашата кръпка

Преди да започнете да работите по своята кръпка, създайте нов клон за промените си.

git checkout -b new_branch_name

Можете да работите върху промяната на кода си.

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

Тестване на промените

Трябва да инсталирате Nette Tester. Най-лесният начин е да извикате composer install в главното хранилище. Сега трябва да можете да стартирате тестове с ./vendor/bin/tester в терминала.

Някои тестове може да се провалят поради липса на php.ini. Затова трябва да извикате runner-а с параметър -c и да посочите пътя до php.ini, например ./vendor/bin/tester -c ./tests/php.ini.

След като успеете да стартирате тестовете, можете да реализирате свои собствени или да промените провалянето, за да съответства на новото поведение. Прочетете повече за тестването с Nette Tester в страницата с документация.

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

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

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

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

/path/to/nette-coding-standard/ecs check src tests --config /path/to/nette-coding-standard/coding-standard-php71.yml --fix

Предаване на промените

След като сте променили кода, трябва да предадете промените. Създайте повече предавания, по едно за всяка логическа стъпка. Всеки commit трябва да може да се използва в този си вид – без други commit-ове. Така че съответните тестове също трябва да бъдат включени в същия commit.

Моля, проверете два пъти дали кодът ви отговаря на правилата:

  • Кодът не генерира грешки
  • Кодът ви не нарушава никакви тестове.
  • Промяната в кода ви е тествана.
  • Не извършвате безполезни промени в бялото пространство.

Съобщението за предаване трябва да следва формата Latte: fixed multi template rendering [Closes # 69] т.е:

  • област, последвана от двоеточие
  • целта на предаването в миналото, ако е възможно, започнете с “добавено.”, “поправено.”, “префактурирано.”, променено, премахнато
  • евентуална връзка към тракер на проблеми
  • ако предаването отменя обратната съвместимост, добавете “BC break”.
  • може да има един свободен ред след темата и по-подробно описание, включително връзки към форума.

Изтегляне на искания за допълнения

Ако сте доволни от промените в кода си и извършените от вас промени, трябва да изпратите промените в GitHub.

git push origin new_branch_name

Промените са публични, но трябва да предложите промените си за интегриране в главния клон на Nette. За целта направете заявка за изтегляне. Всяка заявка за изтегляне има заглавие и описание. Моля, посочете някакво описателно заглавие. То често е подобно на името на клона, например “Защита на сигналите срещу CSRF атака”.

Описанието на заявката за изтегляне трябва да съдържа някаква по-конкретна информация за промените в кода ви:

- bug fix? yes/no   <!-- #issue numbers, if any -->
- new feature? yes/no
- BC break? yes/no
- doc PR: nette/docs#???  <!-- highly welcome, see https://nette.org/en/writing -->

Моля, променете информационната таблица, за да съответства на вашата заявка за изтегляне. Коментари към всеки елемент от списъка:

  • Пише дали заявката за изтегляне добавя функция или е поправка на грешка.
  • Позовава се на евентуално свързан проблем, който ще бъде затворен след обединяването на заявката за изтегляне.
  • Казва дали заявката за изтегляне се нуждае от промени в документацията, ако да, предоставя препратки към съответните заявки за изтегляне. Не е необходимо да предоставяте промените в документацията веднага, обаче заявката за изтегляне няма да бъде обединена, ако са необходими промени в документацията. Промяната в документацията трябва да бъде подготвена за документация на английски език, други езикови мутации не са задължителни.
  • Казва, ако заявката за изтегляне създава прекъсване на БК. Моля, считайте всичко, което променя публичния интерфейс, за прекъсване на БК.

Окончателната таблица може да изглежда така:

- bug fix? no
- new feature? yes   issue #123
- BC break? no

Преработване на промените

Много често се случва да получавате коментари към промените в кода си. Моля, опитайте се да следвате предложените промени и преработете своите ангажименти, за да го направите. Можете да ангажирате предложените промени като нови ангажименти и след това да ги смачкате към предишните. Вижте главата Интерактивно преизчисляване в GitHub. След като ребазирате промените си, форсирайте промените си към отдалеченото си разклонение, като всичко ще се разпространи автоматично към заявката за изтегляне.