Как внести вклад в код

Вы собираетесь внести свой вклад в Nette Framework и вам нужно разобраться в правилах и процедурах? Это руководство для начинающих шаг за шагом покажет вам, как эффективно вносить вклад в код, работать с репозиториями и внедрять изменения.

Процедура

Для внесения вклада в код необходимо иметь учетную запись на GitHub и быть знакомым с основами работы с системой контроля версий Git. Если вы не владеете работой с Git, вы можете ознакомиться с руководством git – простое руководство и, при необходимости, использовать один из множества графических клиентов.

Подготовка среды и репозитория

на GitHub создайте форк репозитория пакета, который вы собираетесь изменить
этот репозиторий клонируйте на свой компьютер
установите зависимости, включая 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: fixed AJAX detection [Closes #69]

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

Описание pull request

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

Также отобразится заголовок, где укажите, является ли это новой функцией или исправлением ошибки, и может ли произойти нарушение обратной совместимости (BC break). Если есть связанная проблема (issue), ссылайтесь на нее, чтобы она была закрыта после одобрения pull request.

- bug fix / new feature?  <!-- #issue numbers, if any -->
- BC break? yes/no
- doc PR: nette/docs#?    <!-- highly welcome, see https://nette.org/en/writing -->