Як зробити внесок у код

Ви збираєтеся зробити внесок у Nette Framework і вам потрібно розібратися в правилах та процедурах? Цей посібник для початківців крок за кроком покаже вам, як ефективно робити внесок у код, працювати з репозиторіями та впроваджувати зміни.

Процедура

Для того, щоб зробити внесок у код, необхідно мати обліковий запис на GitHub та бути знайомим з основами роботи з системою контролю версій Git. Якщо ви не володієте роботою з Git, можете ознайомитися з посібником git – the simple guide та, за потреби, скористатися одним з багатьох графічних клієнтів.

Підготовка середовища та репозиторію

на GitHub створіть fork репозиторію пакета, який ви збираєтеся змінити
цей репозиторій клонуєте на свій комп'ютер
встановіть залежності, включно з Nette Tester, за допомогою команди composer install
перевірте, чи працюють тести, запустивши composer tester
створіть нову гілку на основі останньої випущеної версії

Реалізація власних змін

Тепер ви можете внести свої власні зміни до коду:

запрограмуйте необхідні зміни та не забудьте про тести
переконайтеся, що тести проходять успішно, за допомогою composer tester
перевірте, чи код відповідає стандарту кодування
збережіть зміни (зробіть коміт) з описом у цьому форматі

Ви можете створити кілька комітів, по одному для кожного логічного кроку. Кожен коміт повинен бути осмисленим сам по собі.

Надсилання змін

Як тільки ви будете задоволені змінами, можете їх надіслати:

надішліть (push) зміни на GitHub у ваш форк
звідти надішліть їх до репозиторію Nette, створивши pull request (PR)
надайте в описі достатньо інформації

Врахування зауважень

Ваші коміти тепер побачать і інші. Зазвичай ви отримуватимете коментарі із зауваженнями:

слідкуйте за запропонованими змінами
врахуйте їх як нові коміти або об'єднайте з попередніми
знову надішліть коміти на GitHub, і вони автоматично з'являться в pull request

Ніколи не створюйте новий pull request для зміни існуючого.

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

Якщо ви змінили функціональність або додали нову, не забудьте також додати це до документації.

Нова гілка

Якщо це можливо, вносьте зміни щодо останньої випущеної версії, тобто останнього тегу в даній гілці. Для тегу 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: виправлено виявлення AJAX [Closes #69]

область, за якою слідує двокрапка
мета коміту в минулому часі, якщо можливо, почніть зі слова: added (додано нову властивість), fixed (виправлення), refactored (зміна в коді без зміни поведінки), changed, removed
якщо коміт порушує зворотну сумісність, додайте “BC break”
можливий зв'язок з трекером проблем, як (#123) або [Closes #69]
за темою може слідувати один порожній рядок, а потім детальніший опис, включно з, наприклад, посиланнями на форум

Опис pull request

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

Також відобразиться заголовок, де вкажіть, чи це нова функція, чи виправлення помилки, і чи може відбутися порушення зворотної сумісності (BC break). Якщо є пов'язана проблема (issue), посилайтеся на неї, щоб її було закрито після схвалення pull request.

- виправлення помилки / нова функція?  <!-- #номери issue, якщо є -->
- BC break? так/ні
- doc PR: nette/docs#?    <!-- дуже вітається, див. https://nette.org/en/writing -->