Встановіть стек ПЗ

Перед початком роботи в 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.

Оберіть правильну гілку

• Якщо ви виправляєте баг в існуючій функції, або хочете зробити зміну, яка підпадає під список прийнятних змін у версіях патчів, оберіть найстаршу утримувану проблемну гілку (ви можете знайти їх на сторінці релізів 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, не проводьте злиття; і форсуйте відправку до джерела:

1
2

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

Раніше модератори просили вас "стискати" ваші відправки. Це означає, що ви будете перетворювати багато відправок на одну. Сьогодні це більше не потрібно, так як проект Symfony використовує власний інструмент, який автоматично стискає всі відправки перед злиттям.