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