Створення pull request

Примітка:

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

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

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

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

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

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

flowchart LR A([fa:fa-user Новий
учасник]) --- id1[(kubernetes/website
GitHub)] subgraph tasks[Зміни за допомогою GitHub] direction TB 0[ ] -.- 1[1. Редагувати цю сторінку] --> 2[2. Використовуйте GitHub markdown
редактор для внесення змін] 2 --> 3[3. Виберіть Commit changes...] end subgraph tasks2[ ] direction TB 4[4. Оберіть Propose changes] --> 5[5. Оберіть Create pull request] --> 6[6. Заповніть форму Open a pull request] 6 --> 7[7. Оберіть Create pull request] end id1 --> tasks --> tasks2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class A,1,2,3,4,5,6,7 grey class 0 spacewhite class tasks,tasks2 white class id1 k8s

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

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

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

  3. Праворуч над редактором, оберіть Commit changes. У першому полі дайте заголовок вашому повідомленню коміту. У другому полі надайте опис.

    Примітка:

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

  4. Оберіть Propose changes.

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

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

    • Поле Add a title pull request стандартно містить заголовок коміту. Ви можете змінити його за потреби.
    • Поле Add a description містить розширене повідомлення коміту, якщо у вас є, і деякий текст шаблону. Додайте деталі, які вимагає текст шаблону, потім видаліть зайвий текст шаблону.
    • Залиште прапорець 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 показує кроки, які слід виконати під час роботи з локальним форком. Деталі кожного кроку наведені нижче.

flowchart LR 1[Форк репо kubernetes/website] --> 2[Створіть локальну копію
і встановіть upstream] subgraph changes[Ваші зміни] direction TB S[ ] -.- 3[Створіть гілку
наприклад: my_new_branch] --> 3a[Внесіть зміни за допомогою
текстового редактора] --> 4["Перегляньте зміни
локально за допомогою Hugo
(localhost:1313)
або створіть образ контейнера"] end subgraph changes2[Коміт / Push] direction TB T[ ] -.- 5[Збережіть коміт] --> 6[Надішліть коміт до
origin/my_new_branch] end 2 --> changes --> changes2 classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold classDef k8s fill:#326ce5,stroke:#fff,stroke-width:1px,color:#fff; classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000 class 1,2,3,3a,4,5,6 grey class S,T spacewhite class changes,changes2 white

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

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

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

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

  1. У вікні термінала, клонуйте ваш форк та оновіть тему Docsy Hugo:

    git clone git@github.com:<github_username>/website.git
cd website

  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, рекомендується попередньо переглянути їх локально. У статті Попередній перегляд локально пояснюється, як запустити вебсайт локально та переглянути запропоновані зміни.

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

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

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

flowchart LR subgraph first[ ] direction TB 1[1. Перейдіть до репозиторію kubernetes/website] --> 2[2. Оберіть New Pull Request] 2 --> 3[3. Оберіть compare across forks] 3 --> 4[4. Оберіть ваш форк з
меню head repository] end subgraph second [ ] direction TB 5[5. Оберіть вашу гілку з
меню compare] --> 6[6. Оберіть Create Pull Request] 6 --> 7[7. Додайте опис
до вашого PR] 7 --> 8[8. Оберіть Create pull request] end first --> second classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px; classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold class 1,2,3,4,5,6,7,8 grey class first,second white

Схема 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

Примітка:

Для отримання додаткової інформації див. Галуження в git - Основи галуження та зливання, Розширене злиття, або запитайте в каналі Slack #sig-docs по допомогу.

Якщо інший учасник вносить зміни до того самого файлу в іншому 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>

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

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

Примітка:

Для отримання додаткової інформації див. Інструменти Git - Переписування історії, або запитайте в каналі Slack #sig-docs по допомогу.

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

Примітка:

Ця тема припускає використання текстового редактора vim.

  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.

Що далі

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