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

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. След като ребазирате промените си, форсирайте промените си към отдалеченото си разклонение, като всичко ще се разпространи автоматично към заявката за изтегляне.