Пропозиція зміни

Дата оновлення перекладу 2024-05-13

Пропозиція зміни

Screencast

Надаєте перевагу відео-туторіалам? Перегляньте серіал Участь у створенні Symfony.

Запит на додавання, скорочено "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 you@example.com

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 git@github.com:USERNAME/symfony.git
  • Додайте вищенаписане сховище в якості віддаленого:
1
2
$ cd symfony
$ git remote add upstream git://github.com/symfony/symfony.git

Перевірте проходження поточних тестів

Тепер, коли Symfony встановлена, перевірте, щоб всі модульні тести нормально проходили у вашому середовищі, як пояснюється у присвяченому цьому документі.

Крок 3: Працюйте над своїм запитом на додавання

Ліцензія

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

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

Перед початком роботи над запитом на додавання, необхідно визначити, у якій саме гілці вам потрібно працювати:

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

    Єдиним виключенням є вихід нової старшої версії Symfony (5.0, 6.0 і т.д.) кожні два роки. Через спеціальний процес розробки цих версій, вам треба буде використовувати попередню молодшу версію для функцій (наприклад, викоистовувати 5.4 замість 6.0, або 6.4 замість 7.0, і т.д.)

Note

Всі виправлення багів, обʼєднаних у гілки обслуговування, також обʼєднуються у новіші гілки на регулярній основі. Наприклад, якщо ви відправляєте PR для гілки 5.4, PR також буде застосовано основною командою до всіх гілок 6.x, які досі утримуються.

Під час фази стабілізації , гілка розробки перебуває у стані у стані заморозки функцій. Будь ласка, допоможіть спільноті підготуватися до релізу нової версії. Якщо ви хочете подати запит запит на додавання нової функції, вам слід націлити його на наступну версію. Наприклад, якщо 6.3 досягло стану заморозки, нові функції мають бути націлені на 6.4. Якщо гілки 6.4 ще не існує, орієнтуйтеся на 6.3 і перебазуйте свої запити, як тільки гілка буде створена.

Створіть гілку теми

Кожний раз, коли ви хочете попрацювати над 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

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 6.x
$ git fetch upstream
$ git merge upstream/6.x
$ git checkout BRANCH_NAME
$ git rebase 6.x

Tip

Замініть 6.х на гілку, яку ви обрали раніше (наприклад, 5.4), якщо ви працюєте над виправленням багу.

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

1
2
$ git add ... # додати розвʼязані файли
$ git rebase --continue

Перевірте, щоб всі тести були успішні та віддалено запуште свою гілку:

1
$ git push --force origin BRANCH_NAME

Виконайте запит на додавання

Тепер ви можете виконати запит на додавання у сховище symfony/symfony GitHub.

Tip

Попіклуйтеся про те, щоб вказати вашому запиту на додавання на symfony:5.4, якщо ви хочете, щоб основна команда додала виправлення багу, представленого у гілці 5.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, не проводьте злиття; і форсуйте відправку до джерела:

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

Note

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

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