Внески у документацію

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

Внески у документацію

Перед вашим першим внеском

До того, як робити внесок, вам потрібно:

  • Зареєструвати безкоштовний акаунт GitHub, який є сервісом, де зберігається документація Symfony.
  • Бути ознайомленим з мовою розмітки reStructuredText, яка використовується для написання документів Symfony. Прочитайте цю статтю, щоб швидко все зрозуміти.

Швидкі онлайн-внески

Якщо ви робите відносно невелику зміну - наприклад, виправляєте друкарську помилку або перефразуєте, найпростіший спосіб зробити свій внесок - це безпосередньо на GitHub! Ви можете зробити це під час читання документації Symfony.

Крок 1. Натисніть на кнопку редагувати цю сторінку у верхньому правому куті і вас буде перенаправлено на GitHub:

Кнопка "Редагувати цю сторінку" знаходиться безпосередньо під першим заголовком.

Крок 2. Якщо це ваш перший внесок, вам потрібно зробити розгалуження сховища. Потім відредагуйте зміст, попередньо перегляньте ваші зміни (кнопкою у верхньому лівому куті) і натисніть на кнопку Зафіксувати зміни.... У спливаючому вікні опишіть ваші зміни і натисніть кнопку Пропонувати зміни.

Крок 3. Тепер GitHub створить гілку та коміт для ваших змін, а також покаже попередній перегляд ваших змін:

Сторінка "Порівняння змін" на GitHub.

Якщо все правильно, натисніть на кнопку Створити запит на додавання.

Крок 4. GitHub відобразить нову сторінку, де ви зможете внести деякі останні зміни до вашого запиту на додавання перед його створенням. Для простих внесків ви можете сміливо ігнорувати ці опції і просто натиснути на кнопку Створити запит на додавання ще раз.

Вітаємо! Ви щойно створили запит на додавання до офіційної документації Symfony! Тепер спільнота розгляне ваш запит і (можливо) запропонує зміни.

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

Ваш перший внесок до документації

У цьому розділі ви дізнаєтеся, як зробити свій внесок у документацію Symfony вперше. У наступному розділі буде описано коротший процес, яким ви будете слідувати у майбутньому для кожного наступного внеску після першого.

Уявімо, що ви хочете покращити посібник зі встановлення. Для того, щоб внести свої зміни, виконайте наступні кроки:

Крок 1. Перейдіть до офіційного сховища документації Symfony, розташованого за адресою github.com/symfony/symfony-docs і натисніть на кнопку Розгалужити, щоб щоб розгалужити репозиторій на ваш особистий обліковий запис. Це потрібно лише коли ви вперше робите внесок у Symfony.

Крок 2. Клонуйте розгалужений репозиторій на вашу локальну машину (у цьому прикладі використовується каталог projects/symfony-docs/ для зберігання документації; змініть це значення відповідно):

1
2
$ cd projects/
$ git clone git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git

Крок 3. Додайте оригінальний репозиторій документів Symfony як "Git віддалений", виконавши цю команду:

1
2
$ cd symfony-docs/
$ git remote add upstream https://github.com/symfony/symfony-docs.git

Якщо все пішло добре, ви побачите наступне при відображенні переліку "віддалених" вашого проекту:

1
2
3
4
5
$ git remote -v
origin  git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git (fetch)
origin  git@github.com:YOUR-GITHUB-USERNAME/symfony-docs.git (push)
upstream  https://github.com/symfony/symfony-docs.git (fetch)
upstream  https://github.com/symfony/symfony-docs.git (push)

Виконавши цю команду, ви отримаєте всі коміти висхідних гілок:

1
$ git fetch upstream

Мета цього кроку - дозволити вам одночасно працювати з офіційним репозиторієм Symfony і над власним розгалуженням. Ви побачите це в дії за мить.

Крок 4. Створіть спеціальну нову гілку для ваших змін. Використовуйте коротку назву для нової гілки, яка легко запам'ятовується (якщо ви виправляєте проблему, про яку було повідомлено, використовуйте fix_XXX як назву гілки, де XXX - номер проблеми):

1
$ git checkout -b improve_install_article upstream/5.4

У цьому прикладі назва гілки буде improve_install_article, а значення upstream/5.4 вказує Git створити цю гілку на основі гілки 5.4 віддаленого upstream, яка є оригінальним репозиторієм документації Symfony.

Виправлення завжди мають базуватися на найстарішій підтримуваній гілці, яка містить помилку. Наразі це гілка 5.4. Якщо ви документуєте нову функцію, перейдіть на першу версію Symfony, яка включала її, наприклад upstream/6.2.

Крок 5. Тепер внесіть зміни до документації. Додавайте, налаштовуйте, перефразовуйте і навіть вилучайте будь-який зміст і намагайтеся зробити все можливе, щоб відповідати вимогам Стандари документації. Потім зафіксуйте ваші зміни!

1
2
3
# if the modified content existed before
$ git add setup.rst
$ git commit setup.rst

Крок 6. Пушніть зміни до вашого розгалуженого репозиторія:

1
$ git push origin improve_install_article

Значення origin - це назва віддаленого Git, який відповідає вашому розгалуженому репозиторію, а improve_install_article - це назва гілки, яку ви створили раніше.

Крок 7. Тепер все готово для ініціювання запиту на додавання. Перейдіть до вашого розгалуженого репозиторія за адресою https://github.com/YOUR-GITHUB-USERNAME/symfony-docs і натисніть на посилання Запити на додавання, розташоване на бічній панелі.

Потім натисніть на велику кнопку Новий запит на додавання. Оскільки GitHub не може вгадати які саме зміни ви хочете запропонувати, виберіть відповідні гілки, де повинні бути застосовані зміни:

Опція вибору базової гілки на сторінці GitHub.

У цьому прикладі базове розгалуження має бути симфонія/symfony-docs, а базова гілка має бути 5`.4, тобто гілкою, яку ви вибрали для внесення змін. Головне розгалуження має бути вашою копією розгалуження ymfony-docs, а гілка порівняння має бути improve_install_article, що є назвою гілки, яку ви створили і в яку ви внесли зміни.

Крок 8. Останнім кроком є підготовка опису запиту на додавання. Короткої фрази або абзацу з описом запропонованих змін буде достатньо, щоб гарантувати, що ваш внесок буде розглянутий.

Крок 9. Тепер, коли ви успішно подали свій перший внесок до документації Symfony, ідіть і святкуйте! Менеджери документації уважно переглянуть вашу роботу в найкоротші терміни і повідомлять вас про про будь-які необхідні зміни.

Якщо вас попросять щось додати або змінити, не створюйте новий запит на додавання. Замість цього переконайтеся, що ви перебуваєте в правильній гілці, внесіть свої зміни і зафіксуйте їх:

1
2
3
4
5
6
$ cd projects/symfony-docs/
$ git checkout improve_install_article

# ... зробіть ваші зміни

$ git push

Крок 10. Після того, як ваш запит на додавання буде прийнято і об'єднано з Symfony, вас буде додано до списку Вкладників документації Symfony. Більше того, якщо у вас є профіль SymfonyConnect ви отримаєте крутий значок документації Symfony.

Ваші наступні внески до документації

Погляньте на себе! Ви зробили свій перший внесок у документацію Symfony! Хто-небудь, влаштуйте вечірку! Ваш перший внесок зайняв трохи більше часу, тому що вам потрібно було вивчити декілька стандартів та налаштувати свій комп'ютер. Але відтепер ваші внески буде додавати набагато легше.

Ось контрольний список кроків, які допоможуть вам у створенні вашого наступного внеску до документації Symfony:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# створіть нову гілку, засновану на найстаршій підтримуваній версії
$ cd projects/symfony-docs/
$ git fetch upstream
$ git checkout -b my_changes upstream/5.4

# ... зробіть ваші зміни

# (опціонально) додайте ваші зміни, якщо це новий зміст
$ git add xxx.rst

# відправте ваші зміни та зафіксуйте їх у вашому розгалуженні
$ git commit xxx.rst
$ git push origin my_changes

# ... перейдіть на GitHub та створіть запит на додавання

# (опціонально) зробіть зміни, запропоновані рецензентами, та відправте їх
$ git commit xxx.rst
$ git push

Після завершення ваших наступних внесків, також спостерігайте за покращенням вашого рейтингу у списку Вкладників документації Symfony. Ви вгадали: після всієї цієї важкої роботи, знову настав час святкувати!

Перегляньте ваші зміни

Репозиторій Symfony автоматично перевіряє кожен запит на додавання на наявність типових помилок, невідповідних слів, синтаксичних проблем у блоках коду тощо.

За бажанням ви також можете зібрати документацію на вашій локальній машині для налагодження проблем або читати документацію офлайн. Для цього дотримуйтесь інструкцій, наведених у файлі README репозиторію symfony-docs.

Поширені запитання

Чому мої зміни так довго розглядаються та/або додаються?

Будь ласка, наберіться терпіння. Це може зайняти до декількох днів, перш ніж ваш запит на додавання буде повністю розглянуто. Після додавання змін може пройти ще кілька годин перш ніж ваші зміни з'являться на сайті Symfony.

Чому я повинен використовувати найстарішу підтримувану гілку замість найновішої?

Відповідно до початкового коду Symfony, репозиторій документації розділений на декілька гілок, що відповідають різним версіям самої Symfony. Найновіша гілка (наприклад, 5.x) містить документацію для гілки розробки коду.

Якщо ви не документуєте функцію, яка з'явилася після версії Symfony 5.4, ваші зміни завжди повинні базуватися на гілці 5.4. Менеджери документації використають необхідну Git-магію, щоб також застосувати ваші зміни до всіх активних гілок документації.

Що робити, якщо я хочу подати свою роботу, не закінчивши її повністю?

Ви можете це зробити. Але, будь ласка, використовуйте один з цих двох префіксів, щоб повідомити рецензентам про стан вашої роботи:

  • [WIP] (Робота в процесі) використовується, коли ви ще не закінчили свій запит на додавання, але ви хочете, щоб він був розглянутий. Запит не буде додано, поки ви не скажете, що він готовий.
  • [WCM] (Очікує злиття коду) використовується, коли ви документуєте нову функцію або зміни, які ще не були прийняті до основного коду. Запит на додавання не буде додано, поки він не буде включений в основний код (або закритий, якщо зміна відхилена).

Чи приймете ви величезний запит на додавання з великою кількістю змін?

По-перше, переконайтеся, що зміни хоч якось пов'язані між собою. В іншому випадку, будь ласка, створіть окремі запити на додавання. У будь-якому випадку, перед тим, як надсилати великі зміни, ймовірно, буде гарною ідеєю відкрити питання в репозиторії документації Symfony, щоб запитати менеджерів, чи згодні вони із запропонованими вами змінами. В іншому випадку, вони можуть відхилити вашу пропозицію після того, як ви доклали стільки зусиль для внесення змін. Ми не хочемо, щоб ви витрачали свій час даремно!