Вклад в код

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

Процедура

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

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

На GitHub создайте форк репозитория пакета, который вы собираетесь изменить
Клонируйте этот репозиторий на свой компьютер
Установите зависимости, включая Nette Tester, с помощью команды composer install.
Убедитесь, что тесты работают, выполнив команду composer tester
Создайте новую ветку на основе последней выпущенной версии

Внедрение собственных изменений

Теперь вы можете внести собственные изменения в код:

Внесите желаемые изменения и не забудьте о тестах
Убедитесь, что тесты успешно выполняются composer tester
Проверьте, соответствует ли код стандартам кодирования
Сохраните (зафиксируйте) изменения с описанием в таком формате

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

Представление изменений

После того как вы будете удовлетворены изменениями, вы можете отправить их:

Внесите изменения на GitHub в свой форк.
Оттуда отправьте их в репозиторий Nette, создав pull request внесение изменений (PR).
Предоставьте достаточную информацию в описании

Включение обратной связи

Теперь ваши коммиты видны другим. Часто можно получить комментарии с предложениями:

Следить за предлагаемыми изменениями
Включить их в новые коммиты или объединить с предыдущими
Повторно отправить исправления на GitHub, и они автоматически появятся в запросе на исправление.

Никогда не создавайте новый 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”
любая связь с трекером проблем, например, (#123) или [Closes #69]
после темы может быть одна пустая строка, за которой следует более подробное описание, включая, например, ссылки на форум

Описание Pull Request

При создании 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 -->