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

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

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

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

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

1
2

$ git config --global user.name "Your Name"
$ git config --global user.email you@example.com

1

$ git config core.autocrlf

1

$ git config --global core.autocrlf input

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

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

• Создайте аккаунт GitHub и войдите в него;
• Разветвите хранилище Symfony (нажмите на кнопку "Fork");
• После выполнения "действия разветвления", клонируйте ветку локально (это создаст каталог symfony):

1

$ git clone git@github.com:USERNAME/symfony.git

• Добавьте вышестоящее хранилище в качестве удаленного:

1
2

$ cd symfony
$ git remote add upstream git://github.com/symfony/symfony.git

Проверьте выполнение текущих тестов

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

Лицензия

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

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

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

• Если вы исправляете баг для существующей функции или хотите сделать изменение, которое подпадает под список приемлемых изменений в версиях патчей, выберите самую старую обслуживаемую ветку (вы можете найти их на
  странице релизов Symfony). Например, если вы нашли баг, представленный в v5.1.10, вам нужно работать в 5.4.

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

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

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

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

1

$ git checkout -b BRANCH_NAME 6.1

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

1

$ git checkout --track origin/4.4

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

1

$ git checkout -b BRANCH_NAME 4.4

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

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

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

1

$ php link /path/to/your/project

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

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

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

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

• Пишите хорошие сообщения отправки: начните с краткой строки субъекта (первая строка), за которой следует пустая строка и более детальное описание.

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

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

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

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

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

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

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

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

1
2
3
4
5

$ git checkout 6.1
$ git fetch upstream
$ git merge upstream/6.1
$ git checkout BRANCH_NAME
$ git rebase 6.1

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

1
2

$ git add ... # добавить разрешённые файлы
$ git rebase --continue

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

1

$ git push --force origin BRANCH_NAME

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

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

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

1
2

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

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

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

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

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

1
2
3

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

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

1
2

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

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

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

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

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

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

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/6.1
$ git push --force origin BRANCH_NAME

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