Внесок до Коду

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

Порядок дій

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

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

  1. На GitHub створіть форк сховища пакунків, який ви збираєтеся модифікувати
  2. Клонуйте цей репозиторій на свій комп'ютер
  3. Встановіть залежності, включаючи Nette Tester, за допомогою команди composer install
  4. Переконайтеся, що тести працюють, запустивши їх composer tester
  5. Створіть нову гі лку на основі останньої випущеної версії

Впровадження власних змін

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

  1. Впроваджуйте бажані зміни і не забувайте про тести
  2. Переконайтеся, що тести успішно запускаються за допомогою composer tester
  3. Перевірте, чи відповідає код стандартам кодування
  4. Збережіть (зафіксуйте) зміни з описом у такому форматі

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

Подання змін

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

  1. Перенесіть зміни на GitHub у свій форк
  2. Звідти відправте їх до репозиторію Nette, створивши pull request (PR)
  3. Надайте достатньо інформації в описі

Включення зворотного зв'язку

Ваші комміти тепер видимі для інших. Ми часто отримуємо коментарі з пропозиціями:

  1. Відстежуйте запропоновані зміни
  2. Включіть їх як нові комміти або об'єднайте з попередніми
  3. Повторно надішліть коміти на GitHub, і вони автоматично з'являться в запиті на витягування

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

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

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

Нова гілка

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

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

Опис запиту на витягування

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

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

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->
  1. Документація
  2. Станьте дописувачем Nette
  3. Внесок до Коду