Створення нового контенту

• 1: Створення pull request
• 2: Документування функцій для випуску
• 3: Подання прикладів використання

1 - Створення 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:

   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. Попередній перегляд дозволяє виявити помилки збирання або проблеми з форматуванням 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.

Що далі

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

2 - Документування функцій для випуску

Кожен великий випуск Kubernetes вводить нові функції, які потребують документації. Нові випуски також приносять оновлення наявних функцій і документації (наприклад, оновлення функції з alpha до beta).

Зазвичай робоча група SIG, відповідальна за функцію, подає чернетку документації функції як pull request до відповідної гілки розробки репозиторію kubernetes/website, а хтось з команди SIG Docs надає редакторський відгук або безпосередньо редагує чернетку. Цей розділ охоплює конвенції з гілками та процес, що використовуються під час релізу обома групами.

Щоб дізнатися про анонсування функцій у блозі, прочитайте про комунікацію після випуску.

Для авторів документації

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

Після того як ви вибрали функцію для документування або допомоги, запитайте про це в каналі Slack #sig-docs, на щотижневій зустрічі SIG Docs або безпосередньо в PR, поданому для функції SIG. Якщо вам дозволено, ви можете редагувати PR, використовуючи один з методів, описаних у внесення змін в PR іншої особи.

Дізнайтеся про майбутні функції

Щоб дізнатися про майбутні функції, відвідуйте щотижневу зустріч SIG Release (див. сторінку Спільнота для отримання інформації про майбутні зустрічі) і слідкуйте за документацією, що стосується випуску, в репозиторії kubernetes/sig-release. Кожен випуск має вкладену теку в теці releases. У теці міститься розклад випуску, чернетка приміток до випуску та документ, в якому перераховані всі учасники команди випуску.

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

Цей документ також містить посилання на Feature tracking sheet, що є офіційним способом дізнатися про всі нові функції, заплановані для включення в випуск.

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

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

Лист відстеження функцій

Лист відстеження функцій для конкретного випуску Kubernetes перераховує кожну функцію, заплановану для випуску. Кожен пункт включає назву функції, посилання на основний тікет функції на GitHub, її рівень стабільності (Alpha, Beta або Stable), SIG і особу, відповідальну за її реалізацію, чи потрібна документація, чернетку примітки до випуску для функції та інформацію про те, чи була вона злитою. Памʼятайте наступне:

• Функції Beta і Stable зазвичай мають вищий пріоритет для документації, ніж функції Alpha.
• Випробувати (і, отже, задокументувати) функцію, яка ще не злилася або вважається завершеною в PR, складно.
• Визначення, чи потрібна функції документація, є ручним процесом. Навіть якщо функція не позначена як така, що потребує документації, вам може знадобитися її задокументувати.

Для розробників або інших учасників SIG

Цей розділ є інформацією для членів інших SIG Kubernetes, які документують нові функції для випуску.

Якщо ви є членом SIG, що розробляє нову функцію для Kubernetes, вам потрібно працювати з SIG Docs, щоб забезпечити документацію вашої функції вчасно для випуску. Перевірте список відстеження функцій або перевірте в каналі Slack Kubernetes #sig-release, щоб ознайомитись з деталями планування та строками.

Створіть попередній PR

1. Створіть pull request чернетку на основі гілки dev-1.34 в репозиторії kubernetes/website, з невеликим комітом, який ви пізніше виправите. Щоб створити pull request чернетку, скористайтеся спадним меню Create Pull Request та виберіть Create Draft Pull Request, потім натисніть Draft Pull Request.
2. Відредагуйте опис pull request, щоб включити посилання на kubernetes/kubernetes PR(и) та тікет(и) kubernetes/enhancements.
3. Залиште коментар у відповідному kubernetes/enhancements тікеті з посиланням на PR, щоб сповістити особу з документації, яка управляє цим випуском, що документація функції готується і повинна бути відстежена для випуску.

Якщо ваша функція не потребує жодних змін документації, переконайтеся, що команда sig-release знає про це, зазначивши це в каналі Slack #sig-release. Якщо функція потребує документації, але PR не створений, функція може бути видалена з віхи (milestone).

PR готовий до рецензування

Коли будете готові, заповніть ваш попередній PR з документацією про функцію та змініть стан PR з чернетки на готовий до рецензування. Щоб позначити pull request як готовий до огляду, перейдіть до блоку злиття і натисніть Ready for review.

Зробіть все можливе, щоб описати вашу функцію та як її використовувати. Якщо вам потрібна допомога в структуризації вашої документації, запитайте в каналі Slack #sig-docs.

Коли ви завершите свій контент, особа з документації, призначена для вашої функції, перегляне його. Щоб забезпечити технічну точність, контент може також вимагати технічного огляду від відповідних SIG. Використовуйте їхні пропозиції, щоб підготувати контент до стану, готового до випуску.

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

Функціональні можливості

Якщо ваша функція є Alpha або Beta функцією і залежить від (уві)вимкнення функціональних можливостей, вам потрібен файл функціональних можливостей для неї в content/en/docs/reference/command-line-tools-reference/feature-gates/. Назва файлу має бути назвою функціональних можливостей з розширенням .md. Ви можете подивитися інші файли, що вже знаходяться в цій теці, щоб отримати підказку про те, як повинен виглядати ваш файл. Зазвичай одного абзацу достатньо; для довших пояснень додайте документацію в інше місце і посилайтеся на неї.

Також, щоб забезпечити, що ваші функціональні можливості зʼявляться в таблиці Функціональні можливості Alpha/Beta, включіть наступні деталі у front matter вашого файлу Markdown:

stages:
  - stage: <alpha/beta/stable/deprecated>  # Вкажіть етап розробки функціональних можливостей
    defaultValue: <true or false>     # Встановіть на true, якщо стандартно увімкнено, false в іншому випадку
    fromVersion: <Version>            # Версія, з якої доступна функціональна можливість
    toVersion: <Version>              # (Необов'язково) Версія до якої функціональна можливість доступна

Для нових функціональних можливостей також необхідний їх окремий опис; створіть новий Markdown файл в content/en/docs/reference/command-line-tools-reference/feature-gates/ (використовуйте інші файли як шаблон).

Коли ви змінюєте функціональну можливість зі стану стандартно вимкнено на стандартно увімкнено, вам також може знадобитися змінити іншу документацію (не лише список функціональних можливостей). Звертайте увагу на такі формулювання, як "Поле exampleSetting є полем beta і є стандартно вимкненим. Ви можете увімкнути його, увімкнувши функціональну можливість ProcessExampleThings."

Якщо ваша функція GA'ed або знята з підтримки (deprecated), додайте додатковий запис stage у блок stages в файлі опису. Переконайтеся, що етапи Alpha та Beta залишаються незмінними. Цей крок переводить функціональну можливість з Функціональних можливостей для Alpha/Beta таблиці до таблиці Функціональних можливостей для стабільних або застарілих функцій. Наприклад:

stages:
  - stage: alpha
    defaultValue: false
    fromVersion: "1.12"
    toVersion: "1.12"
  - stage: beta
    defaultValue: true
    fromVersion: "1.13"
  # Додано `toVersion` до попереднього стану.
    toVersion: "1.18"
  # Додано блок 'stable' для поточного стану.
  - stage: stable
    defaultValue: true
    fromVersion: "1.19"
    toVersion: "1.27"

Зрештою, Kubernetes взагалі перестане включати функціональну можливість. Щоб вказати на видалення функціональної можливості, включіть removed: true у front matter відповідного файлу опису. Ця дія викликає перехід функціональної можливості з розділу Функціональні можливості для стабільних або застарілих функцій до окремої сторінки з назвою Функціональні можливості (вилучені), включаючи його опис.

Усі PR рецензовані та готові до злиття

Якщо ваш PR ще не був злитий у гілку dev-1.34 до крайнього терміну випуску, працюйте з особою з документації, що управляє випуском, щоб зробити це до моменту. Якщо ваша функція потребує документації, а документація ще не готова, функція може бути видалена з віхи (milestone).

3 - Подання прикладів використання

Приклади використання показують, як організації використовують Kubernetes для розвʼязання реальних проблем. Команда маркетингу Kubernetes та члени CNCF разом з вами працюватимуть над усіма прикладами використання.

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

Подання прикладу використання

Ознайомтеся з джерелом наявних прикладів використання.

Ознайомтеся з рекомендаціями щодо написання прикладів використання і надішліть свій запит, як зазначено в інструкції.