Дата обновления перевода 2021-08-04

Предложение изменения

Запрос на включение, сокращенно “PR” - это наилучший способ предоставить исправление ошибки или предложить улучшения в Symfony.

Шаг 1: Проверьте существующие ошибки и запросы на включение

Перед тем, как начать работать над изменением, посмотрите, не поднимал ли эту же тему кто-то еще, или не начал ли он уже работать над PR, путем поиска на GitHub.

Если вы не уверены, или если у вас есть вопросы в течение процесса, пожалуйста, задайте свои вопросы в канале #contribs на Symfony Slack.

Шаг 2: Настройте свое окружение

Установите стек ПО

Перед началом работы в Symfony, настройте дружественное окружение со следующим ПО:

  • Git;
  • PHP версии 7.2.5 или выше.

Сконфигурируйте Git

Настройте информацию пользователя используя ваше реально имя и рабочий адрес электронной почты:

1
2
$ git config --global user.name "Your Name"
$ git config --global user.email [email protected]

Tip

Если вы новичок в Git, мы очень рекомендуем вам прочитать отличную и бесплатную книгу ProGit.

Tip

Если ваш IDE создает файлы конфигурации внутри каталога проекта, вы можете использовать глобальный файл .gitignore (для всех проектов), или файл .git/info/exclude (для каждого проекта), чтобы игнорировать их. См. документацию GitHub.

Tip

Пользователи Windows: при установке Git, установщик спросит, что делать с окончаниями строк, и предложит заменить все LF на CRLF. Это неправильная установка, если в хотите вносить правки в Symfony! Лучше всего выбрать метод как есть (as-is), так Git будет конвертировать ваши строки в те, что в хранилище. Если вы уже установили Git, вы можете проверить значение этой настройки, введя:

1
$ git config core.autocrlf

Это вернет “false”, “input” или “true”; Где “true” и “false” - неправильные значения. Измените их на “input”, введя:

1
$ git config --global core.autocrlf input

Замените –global на –local, если вы хотите установить ее только для активного хранилища.

Получите исходный код Symfony

Получите исходный код Symfony:

  • Создайте аккаунт GitHub и войдите в него;
  • Разветвите хранилище Symfony (нажмите на кнопку “Fork”);
  • После выполнения “действия разветвления”, клонируйте ветку локально (это создаст каталог symfony):
1
$ git clone [email protected]:USERNAME/symfony.git
  • Добавьте вышестоящее хранилище в качестве удаленного:
1
2
$ cd symfony
$ git remote add upstream git://github.com/symfony/symfony.git

Проверьте прохождение текущих тестов

Теперь, когда Symfony установлена, проверьте, чтобы все модульные тесты нормально проходили в вашем окружении, как объясняется в посвященном этому документе.

Tip

Если тесты терпят неудачу, проверьте на Travis-CI, происходит ли то же самое с тестом там. В таком случае вам не нужно беспокоиться о неудачном тесте локально.

Шаг 3: Работайте над своим запросом на включение

Лицензия

До того, как вы начнете, вы должны иметь в виду, что весь код, который вы собираетесь отправлять, должен быть выпущен под лицензией MIT.

Выберите правильную ветку

Перед работой над PR, вы должны определить, над какой веткой вам нужно работать:

  • 4.4, если вы исправляете баг для существующей функции или хотите сделать изменение, которое подпадает под список приемлемых изменений в версиях патчей (вам может понадобиться выбрать более высокую ветку, если функция, которую вы исправляете, была представлена в более поздней версии);

  • 5.x, если вы добавляете новую функцию.

    Единственное исключение - это когда каждые два года выходит новая основная версия Symfony (5.0, 6.0, и т.д.). Из-за особенного процесса разработки этих версий, вам нужно использовать предыдущую младшую версию для функци (например, используйте 4.4 вместо 5.0, или 5.4 вместо 6.0, и т.д.).

Note

Все исправления багов, объединенных в ветви обслуживания, также объединяются в более новые ветки на регулярной основе. Например, если вы отправляете PR для ветки 4.4, PR также будет применен основной командой к ветке 5.x.

Создайте ветку темы

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

1
$ git checkout -b BRANCH_NAME 5.x

Или, если вы хотите предоставить исправление бага для ветки 4.4, для начала отследите удаленную ветку 4.4 локально:

1
$ git checkout --track origin/4.4

Затем создайте новую ветку вне ветки 4.4, чтобы поработать над исправлением бага:

1
$ git checkout -b BRANCH_NAME 4.4

Tip

Используйте описательное имя вашей ветки (ticket_XXX где XXX - это номер билета, по соглашению для исправления багов).

Вышеописанные контрольные команды автоматически изменяют код на новосозданную ветку (проверьте, над какой веткой вы работаете, в git branch).

Используйте вашу ветку в существующем проекте

Если вы хотите протестировать ваш код в существующем проекте, использующему symfony/symfony или компоненты Symfony, вы можете использовать утилиту link, предоставленную хранилищем Git, которое вы клонировали ранее. Этот инструмент сканирует каталог vendor/ вашего проекта, находит пакеты Symfony, которые он использует, и заменяет их на символьные ссылки в хранилище Git.

1
$ php link /path/to/your/project

Перед запуском команды link, убедитесь, что зависимости проекта, который вы хотите отладить, установлены, запустив внутри него composer install.

Tip

Если сивольные ссылки на вашу локальную ветвь Symfony не могут быть разрешены внутри вашего проекта в связи с вашим окружением разработки (например, при использовании Vagrant, где монтируется только каталог текущего проекта), вы можете в качестве альтернативы использовать опцию --copy. Когда вы закончите тестирования кода Symfony в вашем проекте, вы можете использовать опцию --rollback, чтобы откатить ваш проект до изначальных настроек.

Работайте над своим запросом на включение

Работайте над кодом столько, сколько вы хотите, и делайте такой вклад, как вы хотите; но помните следующее:

  • Прочтите о соглашениях Symfony и следуйте стандартам кодирования (используйте git diff --check, чтобы проверить завершающие пробелы – также прочтите совет ниже);
  • Добавьте модульные тесты, чтобы доказать, что баг исправлен, или что новая функция действительно работает;
  • Очень постарайтесь не нарушить обратную совместимость (если вам нужно это сделать, постарайте предоставить слой совместимости для поддержки старого способа) – PR, которые нарушают обратную совместимость имеют меньший шанс на объединение;
  • Совершите атомарные и логически разделенные отправки (используйте силу git rebase, чтобы иметь чистую и логичную историю);
  • Никогда не исправляйте стандарты кодирования в некотором существующем коде, так как это затрудняет пересмотр кода;
  • Пишите хорошие сообщения отправки: начните с краткой строки субъекта (первая строка), за которой следует пустая строка и более детальное описание.

    Строка субъекта должна начинаться с Компонента, Моста или Пакета, над которыми вы работаете, в квадратных скобках ([DependencyInjection], [FrameworkBundle], …).

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

    Вот полный пример субъектной строки: [MagicBundle] Add `MagicConfig`, которая позвляет что-то сокнфигурировать.

Tip

При отправке запросов на включение, fabbot проверяет ваш код на распространенные опечатки и верифицирует, что вы используете стандарты PHP-кодирования, определенные в PSR-1 и PSR-2.

Под описанием запроса на включение публикуется статус с кратким итогом любой обнаруженной проблемы или любых ошибок построения Travis-CI.

Подготовьте ваш запрос на включение к отправке

Если ваш PR не касается исправления бага (к примеру, вы добавляете новую функцию или изменяете уже существующую), он также должен включать в себя следующее:

  • Объяснение изменений в соответствующем(им) файле(ах) CHANGELOG (префикс [BC BREAK] или [DEPRECATION] должен быть использован, когда уместно);
  • Объяснение того, как обновить существующее приложение в соответствующем(их) файле(ах) UPGRADE. если изменения нарушают обратную совместимость или если вы объявлете что-то устаревшим, что в любом случае нарушит обратную совместимость.

Шаг 4: Отправьте ваш запрос на включение

Когда вы почувствуете, что ваш PR готов к отправке, следуйте следующим шагам.

Перебазируйте ваш запрос на включение

Перед отправкой вашего PR, обновите свою ветку (необходимо, если завершение ваших изменений занимает у вас немалое время):

1
2
3
4
5
$ git checkout 5.x
$ git fetch upstream
$ git merge upstream/5.x
$ git checkout BRANCH_NAME
$ git rebase 5.x

Tip

Замените 5.x на ветку, которую вы выбрали ранее (например, 4.4), если вы работаете над исправлением бага.

При выполнении команды rebase, вам может понадобиться исправлять конфликты слияния. git status покажет вам необъединенные файлы. Разрешите все конфликты, а затем продолжите с перебазированием:

1
2
$ git add ... # add resolved files
$ git rebase --continue

Проверьте, чтобы все тесты были успешны и удаленно запушьте свою ветку:

1
$ git push --force origin BRANCH_NAME

Выполните запрос на включение

Теперь вы можете выполнить запрос на включенив хранилище symfony/symfony GitHub repository.

Tip

Позаботьтесь о том, чтобы указать вашему запросу на включение на symfony:4.4, если вы хотите, чтобы основная команда включила исправление бага, основанного в ветке 4.4.

Чтобы облегчить работу основной команде, всегда добавляйте модифицированные компоненты в ваш запрос на включение, вроде как в:

1
2
[Yaml] что-то исправили
[Form] [Validator] [FrameworkBundle] что-то добавили

Запрос на включение по умолчанию содержит таблицу, которую вы должны заполнить соответствующими ответами. Это гарантирует, что вклады могут быть рассмотрены без бесполезных циклов фидбека и что ваши вклады могут быть добавлены в Symfony максимально быстро.

Некоторые ответы на вопросы вызывают большее количество требований:

  • Если вы отвечаете “да” на вопрос “Исправление бага?”, посмотрите, указан ли баг уже в списке проблем Symfony и сошлитесь на него/них в “Исправленных билетах”;
  • Если вы отвечаете “да” на вопрос “Новая функция?”, вы должны отправить запрос на включение документации и сослаться на нее в разделе “Doc PR”;
  • Если вы отвечаете “да” на вопрос “Нарушения обратной совместимости?”, то PR должен содержать обновления соответствующих файлов CHANGELOG и UPGRADE;
  • Если вы отвечаете “да” на вопрос “Устаревания?”, PR должен содержать обновления соответствующих файлов CHANGELOG и UPGRADE;
  • Если вы отвечаете “нет” на вопрос “Тест пройден?”, вы должны добавить объект в список дел с действиями, которые должны быть выполнены для исправления тестов;
  • Если “лицензия” - не MIT, просто не отправляйте запрос на включение, так как он в любом случае не будет принят.

Если какие-то из предыдущих требований не будут выполнены, создайте список дел и добавьте релевантные объекты:

1
2
3
- [ ] исправить тесты, так как они еще не были обновлены
- [ ] отправить изменения в документацию
- [ ] задокументировать наружения обратной совместимости

Если ваш код еще не закончен, так как у вас нет времени, или так как вы хотите получить ранний фидбек на свою работу, добавьте объект в ваш список дел:

1
2
- [ ] закончить код
- [ ] получить фидбек на мои изменения

Если у вас есть объекты в списке дел, пожалуйста, добавляйте к запросу на включение префикс “[WIP]”.

В описании запроса на включение, предоставьте максимальное количество деталей о ваших изменениях (не стесняйтесь предоставлять примеры кода для иллюстрации своих мыслей). Если ваш запрос на включение касается добавления новой функции или изменения уже существующей, объясните логику изменений. Описание запроса на включение помогает пересмотру кода и служит справочником при слиянии кода (описание запроса на включение и все ассоциированные с ним комментарии являются частью сообщения отправки слияния).

В дополнение к этому “коду” запроса на включение, вы также должны добавить запрос на включение в хранилище документации, чтобы обновить документацию, когда это необходимо.

Шаг 5: Получите фидбек

Мы просим всех контрибуторов следовать некоторым лучшим практикам, чтобы гарантировать конструктивный процесс фидбека.

Если вы думаете, что кто-то не придерживается этого совета, и вы хотите другую точку зрения, пожалуйста, присоединитесь к каналу #contribs на Symfony Slack. Если вы получите фидбек, который сочтете оскорбительным, свяжитесь с командой CARE.

Основная команда отвечает за то, какие PR будут слияться, поэтому их фидбек самый важный. Поэтому не стоит спешить менять код сразу после получения чьего-либо фидбека.

Автоматизированный фидбек

Существует множество автоматизированных скриптов, которые могут предоставить фидбек на запросы на включение.

fabbot

fabbot просмотрит стиль кода, проверит на наличие распространенных опечаток, и убедится в том, что история git выглядит хорошо. Если есть какие-то проблемы, fabbot зачастую подскажет вам, какие изменения стоит внести. В большинстве случаев вы получите команду, запуск которой автоматически исправит изменения.

Это бывает редко, но иногда fabbot ошибается. Стоит убедиться, что он предлагает изменения, которые имеют смысл, и что они имеют отношения к запросу на включение.

Psalm

Psalm прокомментирует запрос на включение, если обнаружит какие-то потенциальные ошибки. Ошибки Psalm не всегда верны, но каждую стоит рассмотреть и обсудить. Запрос на включение не должен обновлять базовый уровень Psalm или добавлять аннотации @psalm-.

После того, как будет установлен Psalm phar, анализ может быть запущен локально:

1
$ psalm.phar src/Symfony/Component/Workflow

Автоматизированные тесты

При отправке запроса на включение будет запущена серия автоматизированных тестов. Они тестируют код при разных условиях, чтобы гарантировать, что не сломано ничего важного. Неудачи тестирования могут не иметь отношения к вашим изменениям. Если вы думаете, что это ваш случай, вы можете проверить, имеет ли целевая ветка такие же ошибки и оставить комментарий в вашем PR.

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

PHPUnit / Tests

Эта задача запускается на Ubuntu, используя множество версий PHP (каждая в своей собственной задаче). Задачи выполняют набор тестов так же, как вы будете делать это локально.

Ошибка в этих задачах часто идентифицирует баг в коде.

PHPUnit / Tests (high-deps)

Эта задача проверяет каждый пакет (мост, пакет или компонент) в src/ индивидуально, вызывая composer update и phpunit изнутри каждого пакета.

Ошибка в этой задаче часто обозначает недостающий пакет в composer.json пакета с ошибкой (например, src/Symfony/Bundle/FrameworkBundle/composer.json).

Эта задача также запускает релевантные пакеты, используя тест “flipped” (обозначенный суффиксом ^ в названии пакета). Эти тесты проверяют предыдущий основной релиз (например, 4.4 для запроса на включение в 5.4) и запускает тесты в вашей ветке в качестве зависимости.

Ошибка в этих зеркальных тестах указывает на нарушение обратной совместимости в ваших изменениях.

PHPUnit / Tests (low-deps)

Эта задача также проверяет каждый пакет отдельно, но затем использует composer update --prefer-lowest перед выполнением тестов.

Ошибка в этой задаче зачастую указывает на неправильный диапазон версии или отсутствующий пакет в composer.json неудачного пакета.

continuous-integration/appveyor/pr

Эта задача работает на Windows, используя архитектуру x86 и самую старую поддерживаемую версию PHP. Все тесты для начала запускаются без дополнительных PHP-расширений. Затем, все пропущенные тесты запускаются с использованием необходимых PHP-расширений.

Ошибка в этой задаче зачастую указывает на то, что ваши изменения не поддерживают Windows, x86 или PHP с минимальными расширениями.

Integration / Tests

Тесты интеграции требуют работы других сервисов (например, Redis или RabbitMQ). Эта задача запускает тесты только в группе PHPUnit integration.

Ошибка в этой задаче указывает на бак в коммуникации с этими сервисами.

PHPUnit / Tests (experimental)
Эта задача всегда передается (даже с неудачными тестами) и используется основной командой для подготовки к предстоящим версиям PHP.

Поработайте над своим запросом на включение еще

Основываясь на фидбеке о запросе на включение, вам может понадобиться дополнительная работа над вашим PR. Перед повторной отправкой PR, перебазируйте upstream/5.x или upstream/4.4, не проводите слияние; и форсируйте отправку в иcточник:

1
2
$ git rebase -f upstream/5.x
$ git push --force origin BRANCH_NAME

Note

Когда вы проводите push --force, всегда ясно указывайте имя ветки, чтобы избежать нарушения других веток в хранилище (--force сообщает Git, что вы действительно хотите сделать что-то серьезное, так что используйте его с осторожностью).

Ранее модераторы просили вас “сжимать” ваши отправки. Это означает, что вы будете преобразовывать множество отправок в одну. Сегодня это больше не нужно, так как проект Symfony использует собственный инструмент, который автоматически сжимает все отправки перед слиянием.

Эта документация является переводом официальной документации Symfony и предоставляется по свободной лицензии CC BY-SA 3.0.