Пропонуємо внести зміни до Кодексу

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. Тому вам слід викликати бігун з параметром -c і вказати шлях до php.ini, наприклад ./vendor/bin/tester -c ./tests/php.ini.

Після того, як ви зможете запустити тести, ви можете реалізувати свої власні або змінити непрацюючі, щоб вони відповідали новій поведінці. Детальніше про тестування за допомогою Nette Tester читайте на сторінці документації.

Стандарти кодування

Ваш код повинен відповідати стандартам кодування, що використовуються в Nette Framework. Це легко зробити завдяки автоматизованій перевірці та виправленню помилок. Він вимагає PHP 7.1 і може бути встановлений через 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

Фіксація змін

Після того, як ви змінили код, ви повинні зафіксувати зміни. Створіть більше коммітів, по одному для кожного логічного кроку. Кожен комміт має бути придатним для використання як є – без інших коммітів. Отже, відповідні тести також повинні бути включені в той самий комміт.

Будь ласка, перевірте, чи відповідає ваш код правилам:

Код не генерує жодних помилок
Ваш код не порушує жодного тесту.
Ваша зміна коду протестована.
Ви не вносите непотрібні зміни з пробілами.

Повідомлення про фіксацію має відповідати формату Latte: fixed multi template rendering [Closes # 69] тобто

область, за якою слідує двокрапка
мета комміту в минулому, якщо можливо, починайте зі слів “додано”, “виправлено”, “перероблено”, “змінено”, "вилучено
можливе посилання на трекер випусків
якщо комміт скасовує зворотну сумісність, додайте “BC break”
після теми може бути один вільний рядок і більш детальний опис, включаючи посилання на форум.

Витягнення запиту на комміти

Якщо ви задоволені змінами в коді та комітами, вам потрібно відправити їх на GitHub.

git push origin new_branch_name

Зміни присутні у відкритому доступі, однак, ви повинні запропонувати свої зміни для інтеграції в основну гілку Nette. Для цього створіть pull request. Кожен pull request має назву та опис. Будь ласка, надайте якийсь описовий заголовок. Часто вона схожа на назву гілки, наприклад, “Захист сигналів від 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 -->

Будь ласка, змініть інформаційну таблицю відповідно до вашого pull-запиту. Коментарі до кожного пункту списку:

Зазначає, чи запит додає можливість, чи це виправлення помилки.
Вказує на пов'язану проблему, яка буде закрита після об'єднання запиту.
Показує, чи потребує запит зміни документації, якщо так, надайте посилання на відповідні запити. Вам не обов'язково надавати зміни до документації негайно, однак, якщо вони потрібні, запит не буде об'єднано. Зміна документації повинна бути підготовлена для англійської документації, інші мовні мутації не є обов'язковими.
Каже, якщо pull request створює розрив BC. Будь ласка, розглядайте все, що змінює публічний інтерфейс, як розрив BC.

Фінальна таблиця може виглядати так:

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

Переробляючи свої зміни

Дуже часто ми отримуємо коментарі до змін у коді. Будь ласка, намагайтеся слідувати запропонованим змінам і переробляти свої коміти для цього. Ви можете зафіксувати запропоновані зміни як нові коміти, а потім витіснити їх до попередніх. Дивіться розділ Інтерактивне відновлення на GitHub. Після ребазирования виконайте примусове перенесення змін у віддалений форк, і все буде автоматично поширено в пул-запит.