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

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

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

Сконфигурируйте 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 (нажмите кнопку "Создать новую ветку");
• После окончания "действия разветвления", клонируйте вашу ветку локально (это создаст каталог 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, кроме случаев, когда другое ясно указано в ваших фиксациях.

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

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

• 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

Вышенаписанные команды проверки автоматически переключают код на новосозданную ветку (проверьте ветку, на которой вы работаете, с помощью 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, чтобы иметь чистую и логичную историю);
• Никогда не исправляйте стандарты кодирования в уже существующем коде, так как это усложняет отзыв на код;
• Пишите хорошие сообщения фиксации (см. совет ниже).

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

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

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

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

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

1
2
3
4
5

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

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

1
2

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

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

1

$ git push --force origin BRANCH_NAME

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

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

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

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

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