Отправление патча

Патчи являются наилучшим способом предоставить исправление бага или предложить улучшения в Symfony.

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

Установите стек программного обеспечения

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

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

Caution

До Symfony 2.7, минимально требуемой версией PHP была 5.3.3. До Symfony 3.0 - 5.3.9. Пожалуйста, помните об этом, если вы работаете над исправлением бага для более ранних версий Symfony.

Сконфигурируйте 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! Выбрать метод "оставить как есть" - ваш лучший выбор, так как 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 (нажмите кнопку "Создать новую ветку");
  • После окончания "действия разветвления", клонируйте вашу ветку локально (это создаст каталог symfony):
1
$ git clone [email protected]:USERNAME/symfony.git
  • Добавьте целевое хранилище в качестве удалённого:
1
2
$ cd symfony
$ git remote add upstream git://github.com/symfony/symfony.git

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

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

Шаг 2: Работайте над вашим патчем

Лицензия

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

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

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

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

Note

Все исправления багов, слияющиеся с ветками содержания, также регулярно слияются с более поздними ветками. Например, если вы отправите патч для ветки 2.7, то он также будет применён базовой командой к ветке master.

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

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

1
$ git checkout -b BRANCH_NAME master

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

1
$ git checkout -t origin/2.7

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

1
$ git checkout -b BRANCH_NAME 2.7

Tip

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

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

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

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

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

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

Работайте над вашим патчем

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

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

Tip

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

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

Tip

Хорошее сообщение фиксации состоит из краткого изложения (первая строчка), за необязательно следует пустая строчка и более детальное описание. Краткое изложение должно начинаться с Компонента, над которым вы работаете, в квадратных скобках ([DependencyInjection], [FrameworkBundle], ...). Используйте глагол (fixed ..., added ..., ...), чтобы начать изложение, и не добавляйте точку в конце.

Подготовьте патч к отправке

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

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

Шаг 3: Отправьте ваш патч

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

Перебазируйте ваш патч

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

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

Tip

Замените master веткой, выбранной ранее (например, 2.7), если вы работаете над исправлением бага

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

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

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

1
$ git push --force origin BRANCH_NAME

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

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

Tip

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

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

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

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

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

  • Если вы отвечаете "да" на "Исправление бага?", проверьте, указан ли уже баг в проблемах Symfony и сошлитесь на него в "Исправленных билетах";
  • Если вы отвечаете "да" на "Новая функция?", вы должны отправить запрос на включение в документацию и сослаться на него в разделе "Документы ЗВ";
  • Если вы отвечаете "да" на "Наружения ОС?", то патч должен содержать обновления соответствующих файлов CHANGELOG и UPGRADE;
  • Если вы отвечаете "да" на "Депрекации?", то патч должен содержать обновления соотвтетсвующих файлов CHANGELOG и UPGRADE;
  • Если вы отвечаете "нет" на "Успешны ли тесты?", то вы должны добавить их в список дел с действиями, которые должны быть выполнены, чтобы исправить тесты;
  • Если "лицензия" не MIT, то просто не отправляйте запрос на включение, так как он всё равно не будет принят.

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

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

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

1
2
- [ ] закончить код
- [ ] собрать отзывы на мои изменения

Пока у вас есть объекты в списке дел, пожалуйста, используйте в вашеем запросе на включение префикс "[РВП]".

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

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

Переработайте ваш патч

Основываясь на отзыве о ЗВ, вам может понадобиться переработать ваш патч. До повторной отправки, перебазируйте с помощью upstream/master или upstream/2.7, не объединяйте; и принудительно отправьте в исходник:

1
2
$ git rebase -f upstream/master
$ git push --force origin BRANCH_NAME

Note

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

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

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