Створення pull request

Щоб створити нові сторінки або покращити наявні, відкрийте pull request (PR). Переконайтеся, що ви виконали всі вимоги у розділі Перш ніж почати.

Якщо ваша зміна невелика або ви незнайомі з git, прочитайте Зміни за допомогою GitHub, щоб дізнатися, як редагувати сторінку.

Якщо ваші зміни значні, прочитайте Робота з локальним форком, щоб дізнатися, як внести зміни локально на вашому компʼютері.

Зміни за допомогою GitHub

Якщо ви менш досвідчені з робочими процесами git, ось легший спосіб відкрити pull request. На схемі 1 описані кроки, а деталі наведені нижче.

Схема 1. Кроки для відкриття PR за допомогою GitHub.

1. На сторінці, де ви бачите проблему, виберіть опцію Відредагувати сторінку на панелі праворуч.

2. Внесіть зміни у GitHub markdown редакторі.

3. Під редактором заповніть форму Propose file change. У першому полі дайте заголовок вашому повідомленню коміту. У другому полі надайте опис.

   Примітка:

   Не використовуйте жодних ключових слів GitHub у повідомленні вашого коміту. Ви можете додати їх до опису pull request пізніше.

4. Оберіть Propose file change.

5. Оберіть Create pull request.

6. Зʼявиться екран Open a pull request. Заповніть форму:

   • Поле Subject pull request стандартно містить заголовок коміту. Ви можете змінити його за потреби.
   • Поле Body містить розширене повідомлення коміту, якщо у вас є, і деякий текст шаблону. Додайте деталі, які вимагає текст шаблону, потім видаліть зайвий текст шаблону.
   • Залиште прапорець Allow edits from maintainers увімкненим.

   Примітка:

   Опис PR — це чудовий спосіб допомогти рецензентам зрозуміти ваші зміни. Для отримання додаткової інформації див. Відкриття PR.

7. Оберіть Create pull request.

Робота з відгуками на GitHub

Перед злиттям pull request члени спільноти Kubernetes рецензують та схвалюють його. k8s-ci-robot пропонує рецензентів на основі найближчого власника, зазначеного на сторінках. Якщо у вас є конкретна людина на думці, залиште коментар із її імʼям користувача на GitHub.

Якщо рецензент попросить вас внести зміни:

1. Перейдіть на вкладку Files changed.
2. Виберіть іконку олівця (редагування) на будь-якому файлі, зміненому pull request.
3. Внесіть запитані зміни.
4. Збережіть зміни.

Якщо ви чекаєте на рецензента, виходьте на звʼязок хоча б раз на 7 днів. Ви також можете залишити повідомлення у каналі #sig-docs на Slack.

Коли рецензування буде завершено, рецензент зіллє ваш PR і ваші зміни стануть доступними через кілька хвилин.

Робота з локальним форком

Якщо ви більш досвідчені з git або ваші зміни більші за кілька рядків, працюйте з локальним форком.

Переконайтеся, що на вашому компʼютері встановлений git. Ви також можете використовувати застосунок, що є інтерфейсом користувача для git.

Схема 2 показує кроки, які слід виконати під час роботи з локальним форком. Деталі кожного кроку наведені нижче.

Схема 2. Робота з локальним форком для внесення змін.

Форк репозиторію kubernetes/website

1. Перейдіть до репозиторію kubernetes/website.
2. Оберіть Fork.

Створення локальної копії та встановлення upstream

1. У вікні термінала, клонуйте ваш форк та оновіть тему [Docsy Hugo(https://github.com/google/docsy#readme)]:

   git clone git@github.com:<github_username>/website.git
   cd website
   git submodule update --init --recursive --depth 1
   

2. Перейдіть до нової теки website. Встановіть репозиторій kubernetes/website як upstream remote:

   cd website
   
   git remote add upstream https://github.com/kubernetes/website.git
   

3. перевірте ваші origin та upstream репозиторії:

   git remote -v
   

   Вихід буде подібним до:

   origin	git@github.com:<github_username>/website.git (fetch)
   origin	git@github.com:<github_username>/website.git (push)
   upstream	https://github.com/kubernetes/website.git (fetch)
   upstream	https://github.com/kubernetes/website.git (push)
   

4. Отримайте коміти з origin/main вашого форка та upstream/main з kubernetes/website:

   git fetch origin
   git fetch upstream
   

   Це забезпечить актуальність вашого локального репозиторію перед тим, як ви почнете вносити зміни.

   Примітка:

   Цей робочий процес відрізняється від GitHub Workflow спільноти Kubernetes. Вам не потрібно зливати вашу локальну копію main з upstream/main перед тим, як надсилати оновлення до вашого форка.

Створення гілки

1. Виберіть гілку, на якій буде базуватись ваша робота:

   • Для покращення наявного контенту використовуйте upstream/main.
   • Для нового контенту про наявні функції використовуйте upstream/main.
   • Для локалізованого контенту дотримуйтесь домовленостей з локалізації. Для додаткової інформації дивіться локалізацію документації Kubernetes.
   • Для нових функцій у майбутньому випуску Kubernetes використовуйте гілку функцій. Для додаткової інформації дивіться документування релізу.
   • Для довготривалих ініціатив, над якими співпрацюють кілька учасників SIG Docs, таких як реорганізація контенту, використовуйте спеціальну гілку, створену для цього.

   Якщо вам потрібна допомога з вибором гілки, запитайте у каналі #sig-docs в Slack.

2. Створіть нову гілку на основі гілки, визначеної на кроці 1. Цей приклад передбачає, що базова гілка — upstream/main:

   git checkout -b <my_new_branch> upstream/main
   

3. Внесіть свої зміни за допомогою текстового редактора.

У будь-який час використовуйте команду git status, щоб побачити, які файли ви змінили.

Збереження змін

Коли ви готові подати pull request, збережіть ваші зміни.

1. У вашому локальному репозиторії перевірте, які файли потрібно зберегти в репо:

   git status
   

   Вихід буде подібним до:

   On branch <my_new_branch>
   Your branch is up to date with 'origin/<my_new_branch>'.
   
   Changes not staged for commit:
   (use "git add <file>..." to update what will be committed)
   (use "git checkout -- <file>..." to discard changes in working directory)
   
   modified:   content/en/docs/contribute/new-content/contributing-content.md
   
   no changes added to commit (use "git add" and/or "git commit -a")
   

2. Додайте файли, зазначені під Changes not staged for commit, до коміту:

   git add <your_file_name>
   

   Повторіть це для кожного файлу.

3. Після додавання всіх файлів створіть коміт:

   git commit -m "Ваше коміт-повідомлення"
   

   Примітка:

   Не використовуйте жодних GitHub Keywords у вашому повідомленні коміту. Ви можете додати їх до опису pull request пізніше.

4. Надішліть вашу локальну гілку та її новий коміт до вашого віддаленого форку:

   git push origin <my_new_branch>
   

Попередній локальний перегляд змін

Рекомендується попередньо переглянути ваші зміни локально перед тим, як надсилати їх або відкривати pull request. Попередній перегляд дозволяє виявити помилки збирання або проблеми з форматуванням Markdown.

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

• Hugo у контейнері
• Hugo у командному рядку

Відкриття pull request з вашого форку в kubernetes/website

На схемі 3 показано кроки для створення PR із вашого форку в kubernetes/website. Подробиці наведені нижче.

Зверніть увагу, що учасники можуть також згадувати kubernetes/website як k/website.

Схема 3. Кроки для створення PR з вашого форка в kubernetes/website.

1. У веббраузері перейдіть до репозиторію kubernetes/website.

2. Оберіть New Pull Request.

3. Оберіть compare across forks.

4. У спадному меню head repository, оберіть ваш форк.

5. У спадному меню compare, оберіть вашу гілку.

6. Оберіть Create Pull Request.

7. Додайте опис до вашого pull request:

   • Title (50 символів або менше): Стисло опишіть мету зміни.

   • Description: Опишіть зміну докладніше.

     • Якщо є повʼязаний GitHub issue, додайте Fixes #12345 або Closes #12345 в описі. Автоматизація GitHub закриває зазначений тікет після злиття PR, якщо це використано. Якщо є інші повʼязані PR, вкажіть їх також.
     • Якщо ви хочете отримати пораду щодо чогось конкретного, включіть будь-які питання, які б ви хотіли, щоб рецензенти розглянули в описі.

8. Оберіть кнопку Create pull request.

Вітаємо! Ваш pull request доступний у Pull requests.

Після створення PR GitHub запускає автоматичні тести та намагається розгорнути попередній перегляд за допомогою Netlify.

• Якщо збірка Netlify не вдалася, оберіть Details для отримання додаткової інформації.
• Якщо збірка Netlify вдалася, вибір Details відкриває staged версію вебсайту Kubernetes із вашими змінами. Це те, як рецензенти перевіряють ваші зміни.

GitHub також автоматично призначає мітки PR, щоб допомогти рецензентам. Ви також можете додати їх, якщо це потрібно. Для отримання додаткової інформації дивіться Додавання та видалення міток до тікетів.

Робота з відгуками локально

1. Після внесення змін, відредагуйте свій попередній коміт:

   git commit -a --amend
   

   • -a: комітить усі зміни
   • --amend: редагує попередній коміт, замість створення нового

2. За потреби оновіть повідомлення коміту.

3. Використовуйте git push origin <my_new_branch> для надсилання змін і повторного запуску тестів Netlify.

   Примітка:

   Якщо ви використовуєте git commit -m замість редагування, вам потрібно виконати злиття комітів перед злиттям.

Зміни від рецензентів

Іноді рецензенти вносять зміни у ваш pull request. Перед внесенням будь-яких інших змін, отримайте ці коміти.

1. Отримайте коміти з вашого віддаленого форку та виконайте rebase вашої робочої гілки:

   git fetch origin
   git rebase origin/<your-branch-name>
   

2. Після rebase, зробить примусове надсилання нових змін до вашого форку:

   git push --force-with-lease origin <your-branch-name>
   

Конфлікти злиття та rebase

Якщо інший учасник вносить зміни до того самого файлу в іншому PR, це може створити конфлікт злиття. Ви повинні розвʼязати всі конфлікти злиття у вашому PR.

1. Оновіть ваш форк та зробіть rebase вашої локальної гілки:

   git fetch origin
   git rebase origin/<your-branch-name>
   

   Після rebase, зробить примусове надсилання нових змін до вашого форку:

   git push --force-with-lease origin <your-branch-name>
   

2. Отримайте зміни з upstream/main репозиторію kubernetes/website та зробіть rebase у вашій гілці:

   git fetch upstream
   git rebase upstream/main
   

3. Перевірте результати rebase:

   git status
   

   Це призведе до позначення деяких файлів такими, що містять конфлікти.

4. Відкрийте кожен файл з конфліктами та знайдіть маркери конфліктів: >>>, <<< і ===. Розвʼяжіть конфлікт і видаліть маркер конфлікту.

   Примітка:

   Для отримання додаткової інформації див. Як представлені конфлікти.

5. Додайте файли до набору змін:

   git add <filename>
   

6. Продовжіть rebase:

   git rebase --continue
   

7. Повторюйте кроки 2-5 за необхідності.

   Після застосування всіх комітів, команда git status показує, що rebase завершено.

8. Зробить примусове надсилання нових змін до вашого форку:

   git push --force-with-lease origin <your-branch-name>
   

   Пул реквест більше не показує жодних конфліктів.

Обʼєднання комітів

Якщо ваш PR має кілька комітів, ви повинні злити їх в один коміт перед злиттям вашого PR. Ви можете перевірити кількість комітів на вкладці Commits вашого PR або за допомогою команди git log локально.

1. Розпочніть інтерактивний rebase:

   git rebase -i HEAD~<number_of_commits_in_branch>
   

   Злиття комітів є формою rebase. Параметр -i вказує git, що ви хочете виконати інтерактивний rebase. HEAD~<number_of_commits_in_branch> вказує, скільки комітів розглядати для rebase.

   Результат буде схожий на:

   pick d875112ca Original commit
   pick 4fa167b80 Address feedback 1
   pick 7d54e15ee Address feedback 2
   
   # Rebase 3d18sf680..7d54e15ee onto 3d183f680 (3 commands)
   
   ...
   
   # These lines can be re-ordered; they are executed from top to bottom.
   

   Перша частина результату виводить перелік комітів для rebase. Друга частина має параметри для кожного коміту. Заміна слова pick змінює статус коміту після завершення rebase.

   Для цілей rebase зосередьтесь на squash і pick.

   Примітка:

   Для отримання додаткової інформації див. Інтерактивний режим.

2. Розпочніть редагування файлу.

   Змініть початковий текст:

   pick d875112ca Original commit
   pick 4fa167b80 Address feedback 1
   pick 7d54e15ee Address feedback 2
   

   На:

   pick d875112ca Original commit
   squash 4fa167b80 Address feedback 1
   squash 7d54e15ee Address feedback 2
   

   Це зливає коміти 4fa167b80 Address feedback 1 та 7d54e15ee Address feedback 2 у d875112ca Original commit, залишаючи тільки d875112ca Original commit як частину хронології.

3. Збережіть і вийдіть з файлу.

4. Надішліть ваш обʼєднаний коміт:

   git push --force-with-lease origin <branch_name>
   

Беріть участь в інших репо

Проєкт Kubernetes містить понад 50 репозиторіїв. Багато з цих репозиторіїв містять документацію: текст довідки для користувачів, повідомлення про помилки, довідку API або коментарі в коді.

Якщо ви бачите текст, який хочете покращити, скористайтеся GitHub для пошуку по всіх репозиторіях в організації Kubernetes. Це допоможе вам зрозуміти, куди подати ваш тікет або PR.

Кожен репозиторій має свої процеси та процедури. Перед тим як подати тікет або PR, прочитайте README.md, CONTRIBUTING.md та code-of-conduct.md, якщо вони існують.

Більшість репозиторіїв використовують шаблони для тікетів і PR. Подивіться на кілька відкритих тікетів та PR, щоб зрозуміти процеси команди. Обов’язково заповнюйте шаблони з якомога більшою детальністю, коли подаєте тікет або PR.

Що далі

• Прочитайте Рецензування, щоб дізнатися більше про процес рецензування.