Беріть участь в розвитку Kubernetes

• 1: Покращення документації Kubernetes
• 2: Пропозиції щодо покращення вмісту
• 3: Створення нового контенту
• 3.1: Створення pull request
• 3.2: Документування функцій для випуску
• 3.3: Дописи в блог та приклади використань
• 4: Рецензування змін
• 4.1: Рецензування pull request
• 4.2: Рецензування для затверджувачів та рецензентів
• 5: Локалізація документації Kubernetes
• 6: Участь у SIG Docs
• 6.1: Ролі та обовʼязки
• 6.2: Відповідальні за PR
• 6.3: Відповідальні за тікети
• 7: Cтиль документації
• 7.1: Посібник з вмісту документації
• 7.2: Посібник зі стилю документації
• 7.3: Створення діаграм
• 7.4: Написання нової теми
• 7.5: Типи контенту сторінок
• 7.6: Організація контенту
• 7.7: Власні shortcodes Hugo
• 8: Оновлення довідкової документації
• 8.1: Швидкий старт з довідковою документацією
• 8.2: Внесок у код Kubernetes
• 8.3: Генерація документації для API Kubernetes
• 8.4: Генерація документації для команд kubectl
• 8.5: Генерація довідкової документації для метрик
• 8.6: Генерація довідкових сторінок для компонентів та інструментів Kubernetes
• 8.7:
• 9: Розширена участь
• 10: Перегляд аналітики сайту
• 11: Рекомендації з перекладу українською мовою

1 - Покращення документації Kubernetes

Цей вебсайт підтримується робочою групою Kubernetes SIG Docs. Проєкт Kubernetes вітає допомогу від усіх учасників, незалежно від їхнього досвіду!

Учасники, які мають намір працювати з документацією Kubernetes можуть:

• Вдосконалювати наявний вміст
• Створювати новий вміст
• Перекладати документацію
• Керувати та публікувати документацію під час релізного циклу Kubernetes

Початок роботи

Будь-хто може відкрити тікет щодо документації або внести зміни через запит на злиття (PR) в репозиторій GitHub kubernetes/website. Для ефективної роботи в спільноті Kubernetes вам слід вміти працювати з git та GitHub.

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

1. Ознайомтесь та підпишіть CNCF Contributor License Agreement.
2. Ознайомтесь з репозиторієм документації та генератором статичних вебсайтів.
3. Переконайтесь, що ви розумієте базові вимоги щодо відкриття запиту на злиття та процесу рецензування змін.

На схемі 1 зображено шлях для нового учасника. Ви можете виконати деякі або всі етапи з Реєстрації та Огляду. Тепер ви готові відкривати PR (запити на злиття), щоб досягти своїх цілей, деякі з яких перелічені в Створення PR. Знову ж таки, не соромтесь ставити питання, питання завжди вітаються!

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

Ваш перший внесок

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

• Прочитайте Як робити внесок, щоб дізнатися про різні способи, якими ви можете зробити свій внесок.
• Ознайомтесь зі списком тікетів на kubernetes/website на предмет наявності питань, які можуть бути гарними точками входу.
• Відкрийте запит на злиття на GitHub до наявної документації та дізнайтеся більше про створення тікетів на GitHub.
• Рецензуйте запити на злиття від інших учасників спільноти Kubernetes на предмет точності та мови.
• Прочитайте поради щодо вмісту та стилю Kubernetes, щоб залишати обґрунтовані коментарі.
• Дізнайтеся про типи вмісту сторінок та Hugo shortcodes.

Отримання допомоги щодо участі

Зробити перший внесок може бути дуже складно. Помічники для нових учасників (New Contributor Ambassador) готові провести вас через створення вашого першого внеску. Ви можете звертатися до них в Slack Kubernetes, переважно в каналі #sig-docs. Також є Зустрічі з новими учасниками, яка відбувається першого вівторка кожного місяця. Ви можете спілкуватися з помічниками для нових учасників та отримати відповіді на свої запитання там.

Наступні кроки

• Навчіться працювати з локальним клоном репозиторію.
• Документуйте функції у випуску.
• Беріть участь в SIG Docs і станьте учасником або рецензентом.
• Розпочинайте або допомагайте з локалізацією.

Приєднуйтеся до SIG Docs

SIG Docs — це група учасників, які публікують та підтримують документацію Kubernetes та цей вебсайт. Участь в SIG Docs — це гарний спосіб для учасників Kubernetes (розробка функцій чи інше) зробити значний внесок у проєкт Kubernetes.

SIG Docs спілкується за допомогою різних інструментів:

• Приєднуйтесь до #sig-docs в Kubernetes Slack. Не забудьте представитися!
• Приєднуйтесь до списку розсилки kubernetes-sig-docs, де відбуваються ширші обговорення та записуються офіційні рішення.
• Приєднуйтесь до відеозустрічей SIG Docs щотижня. Зустрічі завжди оголошуються в #sig-docs та додаються до календаря зустрічей спільноти Kubernetes. Вам слід завантажити клієнт Zoom або долучитися за допомоги телефону.
• Приєднуйтесь до асинхронних зустрічей в Slack SIG Docs в ті тижні, коли відбувається відеозустріч віч-на-віч. Зустрічі завжди оголошуються в #sig-docs. Ви можете зробити внесок до будь-якого з тредів протягом 24 годин після оголошення зустрічі.

Інші способи зробити внесок

• Відвідайте сайт спільноти Kubernetes. Беріть участь в Twitter або Stack Overflow, дізнайтеся про місцеві зустрічі та події Kubernetes та інше.
• Прочитайте шпаргалку для учасників для участі у розробці функцій Kubernetes.
• Відвідайте сайт учасника, щоб дізнатися більше про учасників Kubernetes та додаткові ресурси для учасників.
• Пишіть пости в блог або в приклади використання.

2 - Пропозиції щодо покращення вмісту

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

У більшості випадків нова робота над документацією Kubernetes починається з тікета на GitHub. Потім учасники Kubernetes переглядають, класифікують та теґують проблеми за потреби. Після цього, ви або інший учасник спільноти Kubernetes відкриваєте pull request зі змінами, щоб розвʼязати проблему.

Створення issue

Якщо ви хочете запропонувати покращення наявного контенту або помітили помилку, створіть тікет.

1. Натисніть Створити тікет на правій боковій панелі. Це перенаправить вас на сторінку issue на GitHub з попередньо заповненими заголовками.
2. Опишіть проблему або пропозицію щодо покращення. Надайте якнайбільше деталей.
3. Натисніть Submit new issue.

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

Пропозиція нового контенту

Якщо у вас є ідея для нового контенту, але ви не впевнені, де його розмістити, ви все одно можете подати тікет. Або:

• Виберіть наявну сторінку в розділі, до якого, на вашу думку, належить контент, і натисніть Створити тікет.
• Перейдіть на GitHub та створіть тікет там.

Як подавати тікети

Майте на увазі наступне під час подання тікета:

• Надайте чіткий опис проблеми. Опишіть, що саме відсутнє, застаріле, неправильне або потребує покращення.
• Поясніть конкретний вплив проблеми на користувачів.
• Обмежте обсяг певного тікета до розумного обсягу роботи. Для проблем великого обсягу розбийте їх на менші тікети. Наприклад, "Виправити документацію з безпеки" занадто широке, а "Додати деталі до теми 'Обмеження доступу до мережі'" достатньо конкретне формулювання, щоб бути здійсненним.
• Пошукайте наявні тікети, щоб побачити, чи є щось повʼязане або схоже на новий тікет.
• Якщо новий тікет стосується іншого тікета або pull request, посилайтеся на нього або через повну URL-адресу, або через номер тікета або pull request з префіксом #. Наприклад, Introduced by #987654.
• Дотримуйтесь Кодексу поведінки. Поважайте інших учасників. Наприклад, "Документація жахлива" — це є корисним чи ввічливим відгуком.

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

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

Схема — Підготовка до створення нового контенту

Вище показана інформація, яку слід знати перед надсиланням нового контенту. Деталі наведені нижче.

Основи участі

• Пишіть документацію Kubernetes у Markdown та збирайте сайт Kubernetes за допомогою Hugo.
• Документація Kubernetes використовує CommonMark варіант Markdown.
• Сирці знаходяться на GitHub. Ви можете знайти документацію Kubernetes в /content/en/docs/. Частина довідкової документації автоматично генерується зі скриптів у теці update-imported-docs/.
• Типи вмісту сторінок описують вигляд вмісту документації в Hugo.
• Ви можете використовувати Docsy shortcodes або власні Hugo shortcodes, щоб зробити внесок у документацію Kubernetes.
• Крім стандартних Hugo shortcodes, ми використовуємо кілька власних Hugo shortcodes у нашій документації для керування процесом обробки вмісту.
• Сирці документації доступні кількома мовами в /content/. Кожна мова має свою теку з дволітерним кодом, визначеним ISO 639-1 стандартом. Наприклад, сирці документації англійською мовою зберігається в /content/en/docs/, української — /content/uk/docs/, відповідно.
• Для отримання додаткової інформації про роботу з документацією кількома мовами або початку нової локалізації, див. локалізація.

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

Підпишіть CNCF CLA

Усі учасники Kubernetes повинні ознайомитись з Настановами для учасників та підписати Угоду про ліцензування внесків (CLA, Contributor License Agreement).

Pull requests від учасників, які не підписали CLA, не пройдуть автоматизовані тести. Імʼя та електронна адреса, які ви надаєте, повинні збігатися з тими, що знаходяться у вашій конфігурації git config, а ваше імʼя та електронна адреса в git повинні збігатися з тими, що використовуються для CNCF CLA.

Оберіть гілку Git для використання

Відкриваючи pull request, ви повинні заздалегідь знати, яку гілку взяти за основу для своєї роботи.

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

Мови в одному PR

Обмежуйте pull requests однією мовою на PR. Якщо вам потрібно внести однакові зміни до одного і того ж зразка коду кількома мовами, відкрийте окремий PR для кожної мови.

Інструменти

Тека інструменти для учасників в репозиторії kubernetes/website містить інструменти, які допоможуть зробити вашу участь в створенні документації простішою.

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(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.

Що далі

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

3.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.32 в репозиторії 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/. Назва файлу має бути назвою функціональних можливостей, перетвореним з UpperCamelCase в kebab-case, с розширенням .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.32 до крайнього терміну випуску, працюйте з особою з документації, що управляє випуском, щоб зробити це до моменту. Якщо ваша функція потребує документації, а документація ще не готова, функція може бути видалена з віхи (milestone).

3.3 - Дописи в блог та приклади використань

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

Блог Kubernetes

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

Кожен може написати блог і подати його на рецензію.

Створення публікації

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

• Нові можливості Kubernetes
• Оновлення проєктів Kubernetes
• Оновлення від робочих груп (Special Interest Groups, SIGs)
• Підручники та керівництва
• Роздуми щодо Kubernetes
• Інтеграція з Kubernetes Partner OSS
• Тільки оригінальний контент

Непридатний контент:

• Комерційні презентації продуктів
• Оновлення від партнерів без інтеграції та історії клієнтів
• Синдиковані пости (переклади різними мовами дозволені)

Щоб подати блог-пост, дотримуйтеся наступних кроків:

1. Підпишіть CLA, якщо ви цього ще не зробили.

2. Ознайомтесь з форматом Markdown для наявних блог-постів у репозиторії вебсайту.

3. Напишіть свій блог у текстовому редакторі за вашим вибором.

4. На тому ж посиланні з кроку 2, натисніть кнопку Створити новий файл. Вставте свій контент у редактор. Назвіть файл відповідно до запропонованої назви блог-посту, але не вказуйте дату у назві файлу. Рецензенти блогу працюватимуть з вами над остаточною назвою файлу та датою публікації блогу.

5. Коли ви збережете файл, GitHub проведе вас через процес pull request.

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

Рекомендації та очікування

• Дописи в блог не повинні бути комерційними презентаціями.

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

• Дописи в блог не публікуються в конкретні дати.

  • Статті рецензуються волонтерами спільноти. Ми намагаємося врахувати конкретні строки, але не даємо жодних гарантій.
  • Багато основних частин проєктів Kubernetes подають дописи під час релізних вікон, що затримує час публікації. Розгляньте можливість подання під час спокійнішого періоду релізного циклу.
  • Якщо вам потрібна більша координація щодо дат випуску постів, координація з маркетингом CNCF є більш відповідним вибором, ніж створення блог-посту.
  • Іноді рецензії можуть затримуватись. Якщо ви відчуваєте, що ваш допис не отримує необхідної уваги, ви можете звернутися до команди блогу на каналі Slack #sig-docs-blog, щоб запитати в реальному часі.

• Дописи в блог повинні бути актуальними для користувачів Kubernetes.

  • Теми, повʼязані з участю або результатами діяльності SIGs Kubernetes, завжди актуальні (дивіться роботу в Команді комунікацій для учасників для підтримки цих дописів).
  • Компоненти Kubernetes є навмисно модульними, тому інструменти, які використовують наявні інтеграційні точки, такі як CNI та CSI, актуальні.
  • Пости про інші проєкти CNCF можуть бути актуальними або ні. Рекомендуємо запитати у команди блогу перед поданням чернетки.
    • Багато проєктів CNCF мають власні блоги. Це часто кращий вибір для постів. Існують випадки важливих функцій або досягнень проєкту CNCF, про які користувачі захочуть дізнатися з блогу Kubernetes.
  • Дописи в блог про внесок до проєкту Kubernetes повинні бути на сайті учасників Kubernetes.

• Дописи в блог повинні бути оригінальним контентом

  • Офіційний блог не призначений для перепрофілювання наявного контенту від інших як нового контенту.
  • Ліцензія для блогу дозволяє використання контенту для комерційних цілей, але не навпаки.

• Дописи в блог повинні бути спрямовані на майбутнє

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

Технічні міркування щодо розміщення допису в блозі

Дописи повинні бути у форматі Markdown, щоб використовуватись генератором Hugo для блогу. Є багато ресурсів з використання цього технологічного стека.

Для ілюстрацій, діаграм або графіків можна використовувати shortcode figure. Для інших зображень ми наполегливо рекомендуємо використовувати атрибути alt; якщо зображення не потребує атрибута alt, можливо, воно взагалі не потрібне в статті.

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

Підпроєкт блогу керує процесом рецензування блог-постів. Для отримання додаткової інформації дивіться Submit a post.

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

• Відкрийте pull request з новим блог-постом. Нові блог-пости розміщуються у теці content/en/blog/_posts.

• Переконайтеся, що ваш блог-пост відповідає чинним домовленостям та містить таку інформацію у frontmatter (метадані):

  • Назва файлу Markdown повинна відповідати формату YYYY-MM-DD-Your-Title-Here.md. Наприклад, 2020-02-07-Deploying-External-OpenStack-Cloud-Provider-With-Kubeadm.md.

  • Не включайте крапки в назву файлу. Назва, як-от 2020-01-01-whats-new-in-1.19.md, викликає помилки під час збірки.

  • Front matter повинен включати наступне:

    ---
    layout: blog
    title: "Your Title Here"
    date: YYYY-MM-DD
    slug: text-for-URL-link-here-no-spaces
    author: >
      Author-1 (Affiliation),
      Author-2 (Affiliation),
      Author-3 (Affiliation)  
    ---
    

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

    • Приклади хорошого опису коміту:
      • Add blog post on the foo kubernetes feature
      • blog: foobar announcement
    • Приклади поганого опису коміту:
      • Add blog post
      • .
      • initial commit
      • draft post

  • Команда блогу потім перегляне ваш PR і надасть вам коментарі щодо речей, які потрібно виправити. Після цього бот обʼєднає ваш PR і ваш блог-пост буде опубліковано.

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

    • Щоб позначити блог-пост як вічнозелений, додайте це до front matter:

      evergreen: true
      

    • Приклади контенту, який не слід позначати вічнозеленим:

      • Підручники, які застосовуються лише до конкретних випусків або версій, а не до всіх майбутніх версій
      • Посилання на API або функції pre-GA

Віддзеркалення з блогу учасників Kubernetes

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

• Залиште вміст блогу таким самим. Якщо є зміни, їх слід внести спочатку до оригінальної статті, а потім до віддзеркаленої статті.
• Віддзеркалений блог-пост повинен мати canonicalUrl, тобто фактично URL оригінального посту після його публікації.
• Так само як і в блогу учасників Kubernetes, дописи в блогах Kubernetes також згадують авторів у заголовку YAML згідно з новими настановами. Потрібно переконатись в їх наявності.
• Дати публікації залишаються такими ж, як в оригінальному блозі.

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

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

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

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

Зверніться до керівництва з підготовки прикладу використання і подайте свій запит, як зазначено в керівництві.

4 - Рецензування змін

Цей розділ описує процес рецензування вмісту.

4.1 - Рецензування pull request

Будь-хто може рецензувати pull request документації. Відвідайте розділ pull requests у репозиторії вебсайту Kubernetes, щоб побачити відкриті pull request.

Рецензування pull request документації — це чудовий спосіб познайомитися зі спільнотою Kubernetes. Це допомагає вам вивчити кодову базу та завоювати довіру інших учасників.

Перед рецензуванням доцільно:

• Ознайомитись з настановами з контенту та керівництвом зі стилю, щоб залишати обґрунтовані коментарі.
• Розуміти різні ролі та обовʼязки у спільноті документації Kubernetes.

Перш ніж почати

Перш ніж почати рецензування:

• Прочитайте Кодекс поведінки CNCF та дотримуйтеся його у будь-який час.
• Будьте ввічливими, уважними та корисними.
• Коментуйте позитивні аспекти PR, а також зміни.
• Будьте емпатичними та враховуйте, як ваш огляд може бути сприйнятий.
• Передбачайте добрі наміри та ставте уточнювальні питання.
• Досвідчені учасники можуть співпрацювати з новими учасниками, чиї роботи потребують значних змін.

Процес рецензування

Загалом, огляньте pull request на вміст та стиль англійською мовою. На схемі 1 показані етапи процесу огляду. Деталі для кожного кроку наведено нижче.

Схема 1. Етапи процесу огляду.

1. Перейдіть на https://github.com/kubernetes/website/pulls. Ви побачите список усіх відкритих pull request до вебсайту та документації Kubernetes.

2. Відфільтруйте відкриті PR, використовуючи одну або всі з наступних міток:

   • cncf-cla: yes (Рекомендовано): PR, подані учасниками, які не підписали CLA, не можуть бути об’єднані з осноною кодовою базою репо. Див. Підписання CLA для отримання додаткової інформації.
   • language/en (Рекомендовано): Фільтрує лише PR англійською мовою.
   • size/<розмір>: фільтрує PR певного розміру. Якщо ви новачок, почніть з менших PR.

   Крім того, переконайтеся, що PR не позначено як роботу в процесі. PR з міткою work in progress ще не готові до огляду.

3. Після того, як ви вибрали PR для огляду, зрозумійте зміни, зроблені в ньому, шляхом:

   • Читання опису PR, щоб зрозуміти зроблені зміни, і читання будь-яких пов’язаних питань
   • Читання коментарів інших рецензентів
   • Клацанням на вкладку Files changed, щоб побачити змінені файли та рядки
   • Попереднього перегляду змін у попередньому перегляді Netlify, прокручуючи до розділу перевірки збірки PR у нижній частині вкладки Conversation. Ось знімок екрана (який показує сайт GitHub на компʼютері; якщо ви переглядаєте на планшеті або смартфоні, вебінтерфейс GitHub дещо відрізняється):

     

     Щоб відкрити попередній перегляд, натисніть на посилання Details у рядку deploy/netlify у списку перевірок.

4. Перейдіть на вкладку Files changed, щоб почати свій огляд.

   1. Клацніть на символ + біля рядка, який хочете прокоментувати.

   2. Додайте ваші коментарі щодо рядка та натисніть або Add single comment (якщо у вас є лише один коментар), або Start a review (якщо у вас є кілька коментарів).

   3. Після завершення натисніть Review changes у верхній частині сторінки. Тут ви можете додати короткий зміст свого огляду (і залишити кілька позитивних коментарів для учасника!).Завжди використовуйте "Comment"

      • Уникайте натискання кнопки "Request changes" при завершенні огляду. Якщо ви хочете заблокувати PR від обʼєднання до внесення подальших змін, ви можете залишити коментар "/hold". Зазначте, чому ви встановлюєте hold, і за потреби уточніть умови, за яких hold можна зняти вами або іншими рецензентами.

      • Уникайте натискання кнопки "Approve" при завершенні огляду. Коментар "/approve" є рекомендованим в більшості випадків.

Контрольний список рецензування

Використовуйте наступні пункти як відправну точку при огляді.

Мова та граматика

• Чи є очевидні помилки в мові або граматиці? Чи є кращий спосіб сформулювати щось?
  • Зосередьтеся на мові та граматиці тих частин сторінки, які змінює автор. Якщо автор не має на меті оновити всю сторінку, він не зобовʼязаний виправляти всі помилки на сторінці.
  • Коли PR оновлює наявну сторінку, слід зосередитися на перегляді тих частин сторінки, які оновлюються. Цей змінений контент слід переглянути на предмет технічної та редакційної відповідності. Якщо ви виявите помилки на сторінці, які не стосуються безпосередньо того, що намагається виправити автор PR, це слід розглядати як окрему проблему (спершу перевірте, чи вже не існує тікет щодо цього).
  • Слідкуйте за pull request, які переміщують контент. Якщо автор перейменовує сторінку або обʼєднує дві сторінки, ми (Kubernetes SIG Docs) зазвичай не просимо до цього автора виправити всі граматичні або орфографічні недоліки в переміщеному контенті.
• Чи є складні або архаїчні слова, які можна замінити простішими?
• Чи є слова, терміни або фрази, які можна замінити на недискримінаційні альтернативи?
• Чи відповідає вибір слів та їхнє написання з великої літери настановам зі стилю?
• Чи є довгі речення, які можна зробити коротшими або менш складними?
• Чи є довгі абзаци, які краще б виглядали у вигляді списку або таблиці?

Вміст

• Чи існує схожий контент в іншому місці на сайті Kubernetes?
• Чи посилається контент надмірно на зовнішні сайти, окремих постачальників або документацію, що не є відкритим вихідним кодом?

Вебсайт

• Чи змінив цей PR заголовок сторінки, slug/alias або anchor link? Якщо так, чи є зламані посилання в результаті цього PR? Чи є інший варіант, наприклад, зміна заголовка сторінки без зміни slug?

• Чи додає PR нову сторінку? Якщо так:

  • Чи використовує сторінка правильний тип контенту сторінки та відповідні Hugo shortcodes?
  • Чи правильно сторінка відображається у боковій навігації (або взагалі)?
  • Чи повинна сторінка з’явитися у списку Docs Home?

• Чи відображаються зміни у попередньому перегляді Netlify? Будьте особливо уважними до списків, блоків коду, таблиць, приміток та зображень.

Блог

• Ранні відгуки щодо дописів блогу вітаються у вигляді Google Doc або HackMD. Будь ласка, запитуйте відгуки заздалегідь у Slack-каналі #sig-docs-blog.

• Перед переглядом PR для блогу ознайомтесь з розділом Надсилання блог-постів і прикладів використання.

• Ми готові розміщувати дзеркальну версію будь-якої статті, опублікованої на https://kubernetes.dev/blog/ (блог спільноти) за умови, що:

  • дзеркальна стаття має ту ж дату публікації, що й оригінал (час публікації також повинен збігатися, але в особливих випадках можна вказати час із затримкою до 12 годин)
  • PR для статей, у яких оригінальна стаття була змерджена на https://kubernetes.dev/, повинні дотримуватись правил:
    • між публікацією оригіналу та дзеркальної статті не було (і не буде) інших публікацій в основному блозі. Це робиться для того, щоб не додавати статті до стрічок, таких як RSS, окрім як у самому кінці.
  • оригінальна стаття не порушує жодних суворо рекомендованих керівних принципів чи норм спільноти.
  • Необхідно вказати канонічний URL для дзеркальної статті, на URL оригінальної статті (можна використовувати попередній перегляд для визначення URL і заповнити його заздалегідь перед публікацією). Використовуйте поле canonicalUrl у front matter для цього.

• Звертайте увагу на цільову аудиторію та те, чи підходить стаття блогу для kubernetes.io. Наприклад, якщо цільовою аудиторією є лише учасники проєкту Kubernetes, то kubernetes.dev може бути більш доречним варіантом, або якщо стаття блогу стосується загальної інженерії платформ, можливо, її краще розмістити на іншому сайті.

  Ці міркування стосуються також дзеркальних статей; хоча ми готові розглянути всі прийнятні статті від учасників для дзеркалювання, якщо відкрито PR, ми не дзеркалюємо всі з них.

• Ми позначаємо статті блогу як підтримувані (evergreen: true у front matter), тільки якщо проєкт Kubernetes готовий зобовʼязатися підтримувати їх необмежений час. Деякі статті блогу безумовно заслуговують на це, і ми завжди позначаємо наші анонси релізів як "evergreen". Порадьтеся з іншими учасниками, якщо ви не впевнені, як перевірити цей аспект.

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

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

  • допустимо використовувати “ми“ в статті блогу, якщо є кілька авторів або вступ чітко вказує, що автор пише від імені певної групи.
  • ми уникаємо використання шорткодів Kubernetes для привернення уваги (наприклад, {{< caution >}})
  • висловлювання про майбутнє допустимі, хоча ми використовуємо їх обережно в офіційних анонсах від імені Kubernetes
  • приклади коду не повинні використовувати шорткод {{< code_sample >}}, і часто краще, щоб вони його не використовували
  • ми дозволяємо авторам писати статті в їхньому власному стилі, за умови, що більшість читачів зрозуміють основну думку

• Посібник зі створення діаграм орієнтований на документацію Kubernetes, а не на статті блогу. Однак:

  • ми надаємо перевагу SVG над растровими форматами діаграм і над Mermaid (джерело Mermaid можна включити у коментар)
  • нема потреби додавати підписи до діаграм як "Рисунок 1", "Рисунок 2" тощо

Інше

• Слідкуйте за несуттєвими правками; якщо ви бачите зміну, яку вважаєте несуттєвою правкою, будь ласка, вкажіть цю політику (все ще можна прийняти зміну, якщо вона дійсно є покращенням).
• Заохочуйте авторів, які роблять виправлення пробілів, робити це в першому коміті свого PR, а потім додавати інші зміни поверх цього. Це полегшує як злиття, так і огляд. Особливо звертайте увагу на несуттєві зміни, які відбуваються в одному коміті разом з великою кількістю виправлень пробілів (і якщо ви це бачите, заохочуйте автора виправити це).

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

Якщо ви розглядаєте pull request для схвалення, і весь відгук позначений як nit, ви можете обʼєднати PR в будь-якому випадку. У такому випадку часто корисно створити тікет щодо залишених незначних зауважень. Розгляньте, чи можете ви виконати вимоги для позначення цієї нової проблеми як Good First Issue; якщо ви можете, це буде хорошим початком для новачків.

4.2 - Рецензування для затверджувачів та рецензентів

Рецензенти та затверджувачі SIG Docs виконують кілька додаткових дій під час огляду змін.

Щотижня конкретний затверджувач документації добровільно погоджується переглядати та рецензувати pull request'и (PR). Ця особа є "PR Wrangler" на тиждень. Детальнішу інформацію можна знайти в розкладі PR Wrangler. Щоб стати PR Wrangler, відвідайте щотижневу зустріч SIG Docs і станьте волонтером. Навіть якщо ви не внесені до розкладу на поточний тиждень, ви все одно можете переглядати pull request'и, які не знаходяться в активному перегляді.

Окрім ротації, бот призначає рецензентів і затверджувачів для PR на основі власників для відповідних файлів.

Огляд PR

Документація Kubernetes дотримується процесу огляду коду Kubernetes.

Все, що описано в Огляд pull request'ів, застосовується, але рецензенти та затверджувачі повинні також робити наступне:

• Використовуйте команду Prow /assign, щоб за потреби призначити конкретного рецензента для PR. Це особливо важливо, коли мова йде про запит технічного огляду від тих хто робить внесок в покращення коду.

  Примітка:

  Подивіться поле reviewers у верхній частині Markdown файлу, щоб побачити, хто може надати технічний огляд.

• Переконайтеся, що PR дотримується настанов з контенту та стилью; надайте автору посилання на відповідну частину керівництва, якщо ні.

• Використовуйте опцію Request Changes в GitHub, коли це доречно, щоб запропонувати зміни автору PR.

• Змінюйте свій статус огляду в GitHub за допомогою команд Prow /approve або /lgtm, якщо ваші пропозиції були впроваджені.

Комміти в PR іншої особи

Залишати коментарі до PR корисно, але можуть бути випадки, коли вам потрібно внести зміни в PR іншої особи.

Не "перебирайте на себе" обовʼязки іншої особи, якщо вона явно не попросить вас про це, або ви хочете відновити давно занедбаний PR. Хоча це може бути швидше в короткостроковій перспективі, це позбавляє людину можливості зробити свій внесок.

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

Ви не можете робити коміти в PR іншої особи, якщо виконується будь-яка з наступних умов:

• Якщо автор PR напряму надіслав (push) свою гілку до https://github.com/kubernetes/website/ репозиторію. Тільки рецензент з доступом на push може робити коміти в PR іншого користувача.

  Примітка:

  Заохочуйте авторів надсилати свою гілку у свій форк перед відкриттям PR наступного разу.

• Автор PR явно забороняє редагування з боку затверджувачів.

Команди Prow для рецензування

Prow є CI/CD системою на базі Kubernetes, яка запускає завдання для pull requestʼів (PR). Prow дозволяє використовувати команди в стилі чат-ботів для обробки дій GitHub у межах організації Kubernetes, таких як додавання та видалення міток, закриття тікетів та призначення затверджувача. Використовуйте команди Prow у вигляді коментарів GitHub у форматі /<command-name>.

Найбільш поширені команди Prow, які використовують рецензенти та затверджувачі:

Щоб переглянути команди, які ви можете використовувати в PR, дивіться довідку по командах Prow.

Класифікація та категоризація проблем

Загалом, SIG Docs дотримується процесу класифікації проблем Kubernetes і використовує ті ж самі мітки.

Цей фільтр GitHub Issue знаходить тікети, які можуть потребувати класифікації.

Класифікація тікета

1. Перевірте тікет

   • Переконайтеся, що запит стосується документації вебсайту. Деякі запити можна швидко вирішити, відповівши на запитання або вказавши на відповідний ресурс. Див. розділ Запити щодо підтримки або повідомлення про помилки в коді для деталей.
   • Оцініть, чи має запит значення.
   • Додайте мітку triage/needs-information, якщо запит не містить достатньо деталей для дій або шаблон не заповнений належним чином.
   • Закрийте тікет, якщо він має мітки lifecycle/stale та triage/needs-information.

2. Додайте мітку пріоритету (докладні визначення міток пріоритету наведено в Issue Triage Guidelines)

   Мітки тікетів

   Мітка	Опис
   priority/critical-urgent	Виконати негайно.
   priority/important-soon	Виконати протягом 3 місяців.
   priority/important-longterm	Виконати протягом 6 місяців.
   priority/backlog	Відкладено на невизначений термін. Виконати, коли будуть ресурси.
   priority/awaiting-more-evidence	Зберегти як потенційно важливу проблему, щоб вона не загубилася.
   help або good first issue	Підходить для тих, хто має дуже мало досвіду з Kubernetes або SIG Docs. Див. Мітки Help Wanted та Good First Issue для отримання додаткової інформації.

   На ваш розсуд, ви можете взяти на себе відповідальність за тікет та створити PR для його вирішення (особливо якщо це швидко або стосується роботи, яку ви вже виконуєте).

Якщо у вас є запитання щодо класифікації тікета, звертайтеся до каналу #sig-docs у Slack або у розсилку kubernetes-sig-docs.

Додавання та видалення міток у тікетів

Щоб додати мітку, залиште коментар в одному з наступних форматів:

• /<label-to-add> (наприклад, /good-first-issue)
• /<label-category> <label-to-add> (наприклад, /triage needs-information або /language ja)

Щоб видалити мітку, залиште коментар в одному з наступних форматів:

• /remove-<label-to-remove> (наприклад, /remove-help)
• /remove-<label-category> <label-to-remove> (наприклад, /remove-triage needs-information)

У обох випадках мітка повинна вже існувати. Якщо ви спробуєте додати мітку, якої не існує, команда буде проігнорована без будь-яких сповіщень проце.

Список усіх міток можна знайти у розділі міток репозиторію сайту. Не всі мітки використовуються SIG Docs.

Мітки життєвого циклу тікета

Тікети зазвичай відкриваються і закриваються швидко. Однак іноді тікети залишаються неактивними після їх відкриття. Іноді тікет може залишатися відкритим більше ніж 90 днів.

Обробка спеціальних типів тікетів

SIG Docs часто стикається з такими типами тікетів, тому важливо знати, як їх обробляти.

Дублікати тікетів

Якщо одна і та ж проблема має один або кілька відкритих тікетів, об’єднайте їх в один тікет. Виберіть тікет, яке слід залишити відкритим (або відкрийте новий), перенесіть всю відповідну інформацію та зв’яжіть пов’язані тікети. Нарешті, позначте всі інші тікети, що описують ту ж проблему, як triage/duplicate і закрийте їх. Наявність єдиного тікета для роботи зменшує плутанину та дозволяє уникнути дублювання роботи над однією і тією ж проблемою.

Проблеми з недійсними посиланнями

Якщо тікет про недійсне посилання стосується документації API або kubectl, присвойте йому мітку /priority critical-urgent, поки проблема не буде повністю зрозуміла. Для всіх інших проблем з недійсними посиланнями використовуйте мітку /priority important-longterm, оскільки їх потрібно виправляти вручну.

Проблеми з блогом

Ми очікуємо, що дописи Kubernetes Blog будуть ставати застарілими з часом. Тому ми підтримуємо дописи блогу лише до одного року. Якщо питання стосується допису, якому понад рік, закрийте тікет без виправлення.

Запити на підтримку або звіти про помилки в коді

Деякі питання з документації насправді є проблемами з основним кодом або запитами про допомогу, коли щось, наприклад, керівництво, не працює. Для питань, які не пов’язані з документацією, закрийте тікет з міткою kind/support та коментарем, що спрямовує запитувача до підтримки (Slack, Stack Overflow) та, якщо це актуально, до репозиторію для створення тікета про помилки з функціями (kubernetes/kubernetes є гарним місцем для початку).

Приклад відповіді на запит про підтримку:

This issue sounds more like a request for support and less like an issue specifically for docs. I encourage you to bring your question to the `#kubernetes-users` channel in [Kubernetes slack](https://slack.k8s.io/). You can also search resources like [Stack Overflow](https://stackoverflow.com/questions/tagged/kubernetes) for answers to similar questions.

You can also open issues for Kubernetes functionality in https://github.com/kubernetes/kubernetes.

If this is a documentation issue, please re-open this issue.

Приклад відповіді на звіт про помилку в коді:

This sounds more like an issue with the code than an issue with the documentation. Please open an issue at https://github.com/kubernetes/kubernetes/issues.

If this is a documentation issue, please re-open this issue.

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

Як затверджувач (approver), коли ви переглядаєте pull requests (PRs), є кілька випадків, коли ви можете зробити наступне:

• Порадити автору обʼєднати коміти.
• Обʼєднати коміти для автора.
• Порадити автору не обʼєднувати коміти ще.
• Запобігти обʼєднанню.

Порада авторам обʼєднати коміти: Нові учасники можуть не знати, що потрібно обʼєднати коміти в своїх pull requests (PRs). Якщо це так, порадьте їм це зробити, надайте посилання на корисну інформацію і запропонуйте допомогу, якщо вона необхідна. Корисні посилання:

• Відкриття pull requests та обʼєднання комітів для учасників документації.
• GitHub Workflow, включаючи діаграми, для розробників.

Обʼєднання комітів для учасників: Якщо автору може бути важко обʼєднати коміти або існує тиск часу для злиття PR, ви можете виконати обʼєднання за них:

• Налаштування репозиторію kubernetes/website дозволяють обʼєднання комітів для pull requests. Все просто — оберіть кнопку Squash commits.
• В PR, якщо автор дозволяє супроводжуючим керувати PR, ви можете обʼєднати їх коміти та оновити їх форк з результатом. Перед обʼєднанням порадьте їм зберегти та надіслати свої останні зміни до PR. Після обʼєднання порадьте їм витягнути обʼєднаний коміт до їх клону.
• Ви можете дозволити GitHub обʼєднати коміти, використовуючи мітку, щоб Tide / GitHub виконали обʼєднання або натиснувши кнопку Squash commits під час злиття PR.

Порада авторам не обʼєднувати коміти

• Якщо один коміт робить щось неправильне або небажане, а останній коміт скасовує цю помилку, не обʼєднуйте коміти. Хоча вкладка "Files changed" в PR на GitHub та перегляд Netlify будуть виглядати нормально, злиття цього PR може створити конфлікти rebases або merges для інших осіб. Втручайтеся, щоб уникнути цього ризику для інших учасників.

Ніколи не обʼєднуйте

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

5 - Локалізація документації Kubernetes

Ця сторінка містить приклади локалізації документації Kubernetes різними мовами.

Покращення наявної локалізації

Ви можете допомогти додати або покращити вміст наявної локалізації. У Slack Kubernetes, ви можете знайти канал для кожної локалізації. Також є загальний канал SIG Docs Localizations, де ви можете привітатись.

Визначте дволітерний код вашої мови

Звіртесь зі стандартом ISO 639-1, щоб знайти дволітерний код вашої мови. Наприклад, дволітерний код для української мови — uk.

Деякі мови використовують версію коду країни у нижньому регістрі, як визначено стандартом ISO-3166, разом з їх мовними кодами. Наприклад, код бразильської португальської мови — pt-br.

Зробіть форк та клонуйте репозиторій

Спочатку, зробіть форк репозиторію kubernetes/website.

Потім клонуйте його собі на компʼютер та перейдіть в локальну теку:

git clone https://github.com/<username>/website
cd website

Вміст сайту включає підтеки для кожної мови. Для локалізації, вам потрібно змінювати вміст в підтеках content/<two-letter-code>.

Пропонуйте зміни

Створіть або оновіть вибрану локалізовану сторінку на основі англійського оригіналу. Дивіться розділ Локалізація вмісту для отримання додаткових вказівок.

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

Обмежте зміни в пул-реквесті однією локалізацією. Розгляд змін, які змінюють вміст у кількох локалізаціях, є проблематичним.

Слідуйте рекомендаціям Пропонування покращення вмісту для пропозиції змін у вмісті локалізації. Це процес подібний до пропозиції змін в оригінальний вміст (англійською мовою).

Створення нової локалізації

Якщо ви хочете мати документацію Kubernetes вашою мовою, ось що вам потрібно зробити.

Оскільки учасники не можуть схвалювати свої власні пул-реквести, вам потрібно принаймні два учасники для початку локалізації.

Всі команди локалізації повинні бути самостійними. Вебсайт Kubernetes радий опублікувати вашу роботу, але вам потрібно перекладати вміст і підтримувати наявний локалізований вміст.

Вам потрібно зʼясувати дволітерний код вашої мови. Зверніться до стандарту ISO 639-1, щоб знайти дволітерний код вашої мови. Наприклад, дволітерний код для української мови — uk.

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

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

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

Пошук спільноти

Дайте знати команді документації Kubernetes, що ви зацікавлені в створенні локалізації! Приєднуйтесь до каналу Slack SIG Docs та каналу Slack SIG Docs Localizations. Інші команди локалізації будуть раді допомогти вам почати та відповісти на ваші питання.

Розгляньте, будь ласка, можливість участі в зустрічі підгрупи локалізації SIG Docs. Місією підгрупи локалізації SIG Docs є співпраця з командами локалізації SIG Docs з метою спільного визначення та документування процесів створення локалізованих посібників. Крім того, підгрупа локалізації SIG Docs розглядає можливості створення та обміну загальними інструментами серед команд локалізації та визначення нових вимог для команди керівників SIG Docs. Якщо у вас є питання щодо цього засідання, будь ласка, запитуйте на каналі Slack SIG Docs Localizations.

Ви також можете створити канал Slack для своєї локалізації в репозиторії kubernetes/community. Для прикладу, як додавати канал в Slack, див. PR для додавання каналу для перської мови.

Приєднуйтесь до організації Kubernetes на GitHub

Коли ви відкрили PR для локалізації, ви можете стати учасниками організації Kubernetes. Кожна особа в команді повинна створити свій власний Запит на членство в організації у репозиторії kubernetes/org.

Додайте свою команду локалізації на GitHub

Далі, додайте свою команду локалізації Kubernetes в sig-docs/teams.yaml. Для прикладу додавання команди локалізації, див. PR для додавання іспанської команди локалізації.

Члени @kubernetes/sig-docs-**-owners можуть схвалювати PR, які змінюють вміст в межах (і лише в межах) вашої теки локалізації: /content/**/. Для кожної локалізації команда @kubernetes/sig-docs-**-reviews автоматизує додавання рецензій для нових PR. Члени @kubernetes/website-maintainers можуть створювати нові гілки локалізації для координації зусиль з перекладу. Члени @kubernetes/website-milestone-maintainers можуть використовувати команду Prow /milestone для призначення віхи завдання чи PR.

Налаштування робочого процесу

Далі, додайте мітку GitHub для вашої локалізації в репозиторії kubernetes/test-infra. Мітка дозволяє вам фільтрувати завдання та пул-реквести для вашої мови.

Приклад додавання мітки для італійської мови.

Зміна конфігурації сайту

Вебсайт Kubernetes використовує Hugo для обслуговування вмісту. Конфігурація вебсайту знаходиться в файлі hugo.toml. Вам потрібно внести зміни у hugo.toml для увімкнення підтримки нової локалізації.

Додайте блок конфігурації для нової мови до hugo.toml в блок [languages]. Наприклад, блок для німецької мови виглядає так:

[languages.de]
title = "Kubernetes"
description = "Produktionsreife Container-Verwaltung"
languageName = "Deutsch (German)"
languageNameLatinScript = "Deutsch"
contentDir = "content/de"
weight = 8

Змінна languageName містить назву мови, яка показується в панелі вибору мови. Вкажіть у languageName назву в форматі "назва мови вашою мовою (назва мови англійською мовою)". Наприклад, languageName = "한국어 (Korean)" або languageName = "Deutsch (German)".

languageNameLatinScript може використовуватись для доступу до мови латиницею та використовувати в темах. Вкажіть "назва мови латиною" у languageNameLatinScript. Наприклад, languageNameLatinScript = "Korean" або languageNameLatinScript = "Deutsch".

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

Для отримання додаткової інформації щодо багатомовної підтримки Hugo дивіться "Multilingual Mode".

Додавання нової теки локалізації

Додайте теку для вашої мови в теку content в репозиторії. Наприклад, дволітерний код для німецької мови — de:

mkdir content/de

Також потрібно створити теку всередині data/i18n для локалізованих рядків; перегляньте наявні локалізації для прикладу. Для використання цих нових рядків, вам також потрібно створити символічне посилання з i18n/<код-мови>.toml на фактичну конфігурацію рядків у data/i18n/<код-мови>/<код-мови>.toml (не забудьте додати символічне посилання в коміт).

Наприклад, для німецької мови рядки знаходяться в data/i18n/de/de.toml, і i18n/de.toml — це символічне посилання на data/i18n/de/de.toml.

Локалізуйте community code of conduct

Створіть пул-реквест в репозиторії cncf/foundation для додавання правил спільноти вашою мовою.

Створіть файли OWNERS

Для призначення ролей кожному учаснику, який вносить внесок у локалізацію, створіть файл OWNERS всередині підтеки, яка відповідає вашій мові, з таким вмістом

• reviewers: Перелік команд kubernetes з роллю рецензентів
  • команду sig-docs-**-reviews створену на кроці Додайте свою команду локалізації на GitHub.
• approvers: Перелік команд kubernetes з роллю, що може затверджувати зміни, в цьому випадку
  • команду sig-docs-**-owners створену на кроці Додайте свою команду локалізації на GitHub.
• labels: Перелік міток, які автоматично додаються до пул-реквестів, в цьому випадку, мітки створені на етапі Налаштування робочого процесу.

Докладніше про файл OWNERS дивіться — go.k8s.io/owners.

Для прикладу файл Spanish OWNERS, з кодом мови es, виглядає так:

# See the OWNERS docs at https://go.k8s.io/owners

# This is the localization project for Spanish.
# Teams and members are visible at https://github.com/orgs/kubernetes/teams.

reviewers:
- sig-docs-es-reviews

approvers:
- sig-docs-es-owners

labels:
- language/es

Після додавання файлу OWNERS для вашої мови, оновіть кореневий файл OWNERS_ALIASES новою командою Kubernetes для локалізації, sig-docs-**-owners та sig-docs-**-reviews.

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

--- a/OWNERS_ALIASES
+++ b/OWNERS_ALIASES
@@ -48,6 +48,14 @@ aliases:
     - stewart-yu
     - xiangpengzhao
     - zhangxiaoyu-zidif
+  sig-docs-es-owners: # Admins for Spanish content
+    - alexbrand
+    - raelga
+  sig-docs-es-reviews: # PR reviews for Spanish content
+    - alexbrand
+    - electrocucaracha
+    - glo-pena
+    - raelga
   sig-docs-fr-owners: # Admins for French content
     - perriea
     - remyleone

Створіть пул-реквест

Далі, створіть пул-реквест (PR) для додавання локалізації в репозиторій kubernetes/website. PR повинен містити мінімально необхідний вміст перед тим, як він може бути схваленим.

Наприклад додавання нової локалізації для французької мови.

Додайте локалізований файл README

Щоб керувати іншими учасниками локалізації, додайте новий README-**.md в корінь репозиторію kubernetes/website, де ** — дволітерний код мови. Наприклад, файл README для української мови буде README-uk.md.

Скеровуйте учасників локалізації до локалізованого файлу README-**.md. Додайте туди ту ж інформацію, що міститься в README.md, а також:

• Контактну інформацію проєкту локалізації
• Будь-яку інформацію, специфічну для локалізації

Після створення локалізованого README, додайте посилання на файл у головний англійський README.md, а також включіть контактну інформацію англійською мовою. Ви можете надати ідентифікатор GitHub, адресу електронної пошти, канал Slack або інший метод звʼязку. Ви також повинні надати посилання на локалізований Кодекс поведінки спільноти.

Запуск вашої нової локалізації

Коли локалізація відповідає вимогам для робочого процесу та мінімальним вимогам щодо вмісту, SIG Docs робить наступне:

• Вмикає на вебсайті відповідний мовний розділ.
• Сповіщає про наявність локалізованого вмісту через канали Cloud Native Computing Foundation (CNCF), включаючи блог Kubernetes.

Локалізація вмісту

Локалізація всього вмісту Kubernetes є неосяжним завданням. Необхідно починати з мінімально необхідного вмісту та поступово розширювати його.

Мінімально необхідний вміст

Як мінімум, всі локалізації мають містити:

Перекладена документація має знаходитись у власній підтеці content/**/ та мати ту ж URL-структуру, що й англійська версія. Наприклад, щоб підготувати Основи Kubernetes для перекладу німецькою мовою, створіть підтеку у content/de та скопіюйте в неї сирці англійської версії:

mkdir -p content/de/docs/tutorials
cp -ra content/en/docs/tutorials/kubernetes-basics/ content/de/docs/tutorials/

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

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

Локалізація зображень SVG

Проєкт Kubernetes рекомендує використовувати векторні (SVG) зображення, де це можливо, оскільки їх набагато легше редагувати командам локалізації. Якщо ви знаходите растрове зображення, яке потрібно локалізувати, розгляньте можливість спочатку перетворення англійської версії у векторне зображення, а потім локалізуйте його.

При перекладі тексту всередині векторних зображень (SVG — Scalable Vector Graphics) важливо дотримуватися певних рекомендацій, щоб забезпечити точність і підтримувати однорідність між різними мовними версіями. Зображення SVG часто використовуються в документації Kubernetes для ілюстрації концепцій, робочих процесів та схем.

1. Визначення тексту для перекладу: Почніть з ідентифікації текстових елементів всередині SVG-зображення, які потрібно перекласти. Зазвичай до цих елементів входять мітки, підписи, анотації чи будь-який текст, що передає інформацію.

2. Редагування файлів SVG: Файли SVG базуються на XML, що означає, що їх можна редагувати за допомогою текстового редактора. Проте важливо враховувати, що більшість зображень в документації Kubernetes вже конвертують текст в криві, щоб уникнути проблем сумісності шрифтів. У таких випадках рекомендується використовувати спеціалізоване програмне забезпечення для редагування SVG, таке як Inkscape. Відкрийте файл SVG у програмі Inkscape та знайдіть елементи тексту, які потребують перекладу.

3. Переклад текстів: Замініть оригінальний текст перекладеною версією бажаною мовою. Переконайтеся, що перекладений текст точно виражає задумане значення і вміщується у вільне простір у зображенні. При роботі з мовами, які використовують латинський алфавіт, слід використовувати сімʼю шрифтів Open Sans. Ви можете завантажити шрифт Open Sans за цим посиланням: Open Sans Typeface.

4. Перетворення тексту в криві: Як вже зазначалося, для розвʼязання проблеми сумісності шрифтів рекомендується конвертувати перекладений текст в криві. Конвертація тексту в криві гарантує правильне відображення перекладеного тексту у кінцевому зображенні, навіть якщо система користувача не має шрифту, використаного в оригінальному SVG.

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

Файли сирців

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

Для пошуку файлів сирців для цільової версії:

1. Перейдіть до репозиторію вебсайту Kubernetes https://github.com/kubernetes/website.

2. Оберіть гілку з вашою цільовою версією користуючись таблицею:

Гілка main містить вміст для поточного релізу v1.31. Команда релізу створює гілку release-1.31 перед наступним релізом: v1.32.

Рядки сайту в i18n

Локалізація має включати вміст data/i18n/en/en.toml у новому файлі для відповідної мови. Наприклад, для німецької мови: data/i18n/de/de.toml.

Додайте нову теку для локалізації та файл до data/i18n/. Наприклад, для німецької мови (de):

mkdir -p data/i18n/de
cp data/i18n/en/en.toml data/i18n/de/de.toml

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

[ui_search_placeholder]
other = "Suchen"

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

Настанови щодо локалізації певною мовою

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

Наприклад, див. Корейський посібник з локалізації, який включає опис таких тем, як:

• Частота спринтів та релізи
• Стратегія створення гілок
• Робота з pull request
• Посібник зі стилю
• Глосарій локалізованих та нелокалізованих термінів
• Конвенції Markdown
• Термінологія обʼєктів Kubernetes API

Зустрічі в Zoom для обговорення локалізації відповідною мовою

Якщо проєкту з локалізації потрібен окремий час на зустрічі, звʼяжіться з одним з координаторів SIG Docs або Tech Lead, щоб створити нову регулярну зустріч в Zoom та запрошення в календар. Це потрібно тільки тоді, коли команда достатньо велика та вимагає окремих зустрічей.

Відповідно до правил CNCF, команди локалізації повинні завантажувати свої зустрічі в плейлист YouTube SIG Docs. Координатор SIG Docs або Tech Lead може допомогти з цим процесом до тих пір, поки SIG Docs не автоматизує його.

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

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

Щоб співпрацювати в гілці локалізації:

1. Член команди @kubernetes/website-maintainers створює гілку локалізації з гілки основного проєкту https://github.com/kubernetes/website.

   Особи з вашої команди, які затверджують зміни, приєднуються до команди @kubernetes/website-maintainers, коли ви створюєте свою команду локалізації до репозиторію kubernetes/org.

   Ми радимо наступну схему найменування гілок:

   dev-<source version>-<language code>.<team milestone>

   Наприклад, затверджувач зміни німецької команди створює гілку для локалізації dev-1.12-de.1 безпосередньо в репозиторії kubernetes/website, яка базується на гілці для Kubernetes v1.12.

2. Індивідуальні учасники створюють гілки-теми на основі гілки локалізації.

   Наприклад, учасник німецькою команди створює пул-реквест зі змінами у kubernetes:dev-1.12-de.1 з username:local-branch-name.

3. Затверджувач переглядає зміни та зливає гілку-тему в гілку локалізації.

4. Періодично затверджувач обʼєднує гілку локалізації зі своєю вихідною гілкою, відкриваючи та затверджуючи новий pull request. Обовʼязково обʼєднуйте (squash) коміти перед затвердженням pull request.

Повторюйте кроки 1-4 за потреби, поки локалізація не буде завершена. Наприклад, наступні гілки локалізації німецькою мовою будуть: dev-1.12-de.2, dev-1.12-de.3 і т.д.

Команди повинні обʼєднувати локалізований вміст у ту гілку, з якої вміст було отримано. Наприклад:

• Гілку локалізації створену з гілки main потрібно заливати у гілку main.
• Гілку локалізації створену з release-1.30 потрібно заливати у release-1.30.

На початку кожного етапу команді корисно відкрити тікет для порівняння висхідних змін між попередньою гілкою локалізації та поточною гілкою. Є два скрипти для порівняння змін.

• upstream_changes.py є корисним для перевірки змін, що були зроблені у відповідному файлі, та
• diff_l10n_branches.py є корисним для створення переліку застарілих файлів для відповідної гілки локалізації.

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

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

Внесення змін до оригінальної документації

Команда SIG Docs вітає внески та виправлення до англійської версії документації.

6 - Участь у SIG Docs

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

SIG Docs вітає контент та рецензування від усіх учасників. Будь-хто може відкрити pull request (PR), і будь-хто може подавати питання щодо контенту або коментувати pull request'и, що знаходяться в процесі.

Ви також можете стати членом, рецензентом або затверджувачем. Ці ролі вимагають більшого доступу і несуть певні обов’язки щодо затвердження та прийняття змін. Дивіться community-membership для отримання додаткової інформації про те, як працює членство в спільноті Kubernetes.

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

Голова SIG Docs

Кожна SIG, включаючи SIG Docs, обирає одного або кількох членів SIG для виконання ролі голови. Ці особи є контактними точками між SIG Docs та іншими частинами організації Kubernetes. Від них вимагається глибоке знання структури проєкту Kubernetes в цілому та того, як SIG Docs працює в ньому. Дивіться Leadership для ознайомлення з актуальним списку голів.

Команди та автоматизація SIG Docs

Автоматизація в SIG Docs покладається на два різних механізми: GitHub команди та файли OWNERS.

Команди GitHub

Існує дві категорії команд SIG Docs у GitHub:

• @sig-docs-{language}-owners є затверджувачами та лідерами
• @sig-docs-{language}-reviews є рецензентами

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

Іноді Prow та команди GitHub збігаються без точного відповідності. Для призначення тікетів, pull request'ів та підтримки затвердження PR автоматизація використовує інформацію з файлів OWNERS.

Файли OWNERS та front-matter

Проєкт Kubernetes використовує автоматизаційний інструмент під назвою prow для автоматизації, повʼязаної з тікетами та pull requestʼами на GitHub. Репозиторій вебсайту Kubernetes використовує два втулки prow:

• blunderbuss
• approve

Ці два втулки використовують файли OWNERS та OWNERS_ALIASES на верхньому рівні репозиторію kubernetes/website GitHub для контролю роботи prow у репозиторії.

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

Крім того, сам Markdown файл може містити список рецензентів та затверджувачів у його front-matter, вказуючи індивідуальні імена користувачів GitHub або групи GitHub.

Комбінація файлів OWNERS та front-matter у файлах Markdown визначає поради, які отримують власники PR від автоматизованих систем щодо того, кого попросити про технічний та редакційний огляд їх PR.

Як працює злиття

Коли pull request зливається з гілкою, що використовується для публікації контенту, цей контент публікується на https://kubernetes.io. Щоб забезпечити високу якість нашого опублікованого контенту, ми обмежуємо злиття pull requestʼів до затверджувачів SIG Docs. Ось як це працює.

• Коли pull request має обидві мітки lgtm та approve, не має міток hold та всі тести проходять успішно, pull request зливається автоматично.
• Члени організації Kubernetes та затверджувачі SIG Docs можуть додавати коментарі для запобігання автоматичного злиття конкретного pull request (додавши коментар /hold або утримуючись від додавання коментаря /lgtm).
• Будь-який член Kubernetes може додати мітку lgtm, додавши коментар /lgtm.
• Тільки затверджувачі SIG Docs можуть зливати pull request, додаючи коментар /approve. Деякі затверджувачі також виконують додаткові ролі, такі як PR Wrangler або голова SIG Docs.

Що далі

Для отримання додаткової інформації про внесок до документації Kubernetes дивіться:

• Внесення нового контенту
• Огляд контенту
• Настанови зі стилю

6.1 - Ролі та обовʼязки

Будь-хто може зробити внесок у Kubernetes. Зі зростанням ваших внесків до SIG Docs, ви можете подати заявку на різні рівні членства в спільноті. Ці ролі дозволяють брати на себе більше відповідальності в спільноті. Кожна роль вимагає більше часу та відданості. Ролі є такими:

• Будь-хто: регулярні учасники документації Kubernetes
• Члени: можуть призначати та розподіляти тікети, а також надавати відгук на pull requestʼи, який не є обовʼязковим до виконання
• Рецензенти: можуть керувати рецензією документаційних pull request'ів і гарантувати якість змін
• Затверджувачі: можуть керувати рецензією документації та зливати зміни

Будь-хто

Будь-хто з обліковим записом GitHub може зробити свій внесок у Kubernetes. SIG Docs вітає всіх нових учасників!

Будь-хто може:

• Створити тікет в будь-якому репозиторії Kubernetes, включаючи kubernetes/website
• Надати відгук на pull request, який не є обовʼязковим для виконання
• Зробити внесок у локалізацію
• Запропонувати покращення у Slack або в списку розсилки SIG docs.

Після підписання CLA, будь-хто також може:

• Створити pull request для покращення наявного контенту, додавання нового контенту або написання блогу чи прикладу використання
• Створювати діаграми, графічні ресурси та вбудовані відеозаписи та відео

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

Члени

Член — це хтось, хто подав кілька pull request'ів до kubernetes/website. Члени є частиною організації Kubernetes на GitHub.

Члени можуть:

• Робити все, що зазначено в розділі Будь-хто

• Використовувати коментар /lgtm, щоб додати мітку LGTM (виглядає добре для мене) до pull request'у

  Примітка:

  Використання /lgtm запускає автоматизацію. Якщо ви хочете надати не обовʼязкове схвалення, коментар "LGTM" також працює!

• Використовувати коментар /hold, щоб заблокувати злиття для pull request'у

• Використовувати коментар /assign, щоб призначити рецензента для pull requestʼу

• Робити рецензування pull request'ів, які не є обовʼязковими

• Використовувати автоматизацію для розподілу та категоризації тікетів

• Документувати нові функції

Набуття членства

Після подання щонайменше 5 значних pull request'ів та виконання інших вимог:

1. Знайдіть двох рецензентів або затверджувачів, які стануть вашими поручителями.

   Попросіть поручительства в каналі #sig-docs на Slack або в списку розсилки SIG Docs.

   Примітка:

   Не надсилайте прямий електронний лист або пряме повідомлення у Slack окремому члену SIG Docs. Ви повинні запитати про поручительство перед поданням вашої заявки на членство.

2. Відкрийте тікет на GitHub у репозиторії kubernetes/org. Використовуйте шаблон тікета Organization Membership Request.

3. Повідомте своїх поручителів про тікет на GitHub. Ви можете:

   • Згадати їх через GitHub-імʼя у тікеті (@<GitHub-username>)

   • Надіслати їм посилання на тікет за допомогою Slack або електронної пошти.

     Поручителі схвалюють ваш запит позначкою +1. Після схвалення запиту вашими поручителями, адміністратор GitHub Kubernetes додає вас як члена. Вітаємо!

     Якщо ваш запит на членство не приймається, ви отримаєте відгук. Після врахування відгуків подайте заявку знову.

4. Прийміть запрошення до організації Kubernetes на GitHub у своєму обліковому записі електронної пошти.

   Примітка:

   GitHub надсилає запрошення на основну електронну адресу у вашому обліковому записі.

Рецензенти

Рецензенти відповідають за рецензування відкритих pull request'ів. На відміну від відгуків членів, автор PR повинен враховувати відгуки рецензентів. Рецензенти є членами команди GitHub @kubernetes/sig-docs-{language}-reviews.

Рецензенти можуть:

• Робити все, що зазначено в розділах Будь-хто та Члени

• Оглядати pull requestʼи та надавати обовʼязковий відгук

  Примітка:

  Щоб надати не обовʼязковий відгук, додайте до ваших коментарів фразу типу "Optionally: ".

• Редагувати рядки, що стосуються користувачів, у коді

• Покращувати коментарі до коду

Ви можете бути рецензентом SIG Docs або рецензентом для документів у певній предметній області.

Призначення рецензентів до pull requestʼів

Автоматизація призначає рецензентів до всіх pull requestʼів. Ви можете запросити огляд від конкретної особи, додавши коментар: /assign [@_github_handle].

Якщо призначений рецензент не прокоментував PR, інший рецензент може втрутитися. Ви також можете призначати технічних рецензентів за потреби.

Використання /lgtm

LGTM означає "Виглядає добре для мене" і вказує, що pull request є технічно точним і готовим до злиття. Усі PR потребують коментаря /lgtm від рецензента та коментаря /approve від затверджувача для злиття.

Коментар /lgtm від рецензента є обовʼязковим і запускає автоматизацію, яка додає мітку lgtm.

Як стати рецензентом

Коли ви відповідаєте вимогам, ви можете стати рецензентом SIG Docs. Рецензенти в інших SIG повинні подавати окрему заявку на статус рецензента в SIG Docs.

Щоб подати заявку:

1. Відкрийте pull request, що додає ваше імʼя користувача GitHub до розділу файлу OWNERS_ALIASES в репозиторії kubernetes/website.

   Примітка:

   Якщо ви не впевнені, де себе додати, додайте себе до sig-docs-en-reviews.

2. Призначте PR одному або кільком затверджувачам SIG Docs (імена користувачів вказані в sig-docs-{language}-owners).

Якщо заявку схвалено, лідер SIG Docs додає вас до відповідної команди GitHub. Після додавання K8s-ci-robot призначає та пропонує вас як рецензента на нові pull requestʼи.

Затверджувачі

Затверджувачі оглядають і затверджують pull requestʼи для злиття. Затверджувачі є членами команд GitHub @kubernetes/sig-docs-{language}-owners.

Затверджувачі можуть робити наступне:

• Все, що зазначено в розділах Будь-хто, Члени та Рецензенти
• Публікувати контент учасників, затверджуючи та зливаючи pull requestʼи за допомогою коментаря /approve
• Пропонувати покращення до посібника зі стилю
• Пропонувати покращення до тестів документації
• Пропонувати покращення до вебсайту Kubernetes або інших інструментів

Якщо PR вже має /lgtm, або якщо затверджувач також додає коментар /lgtm, PR автоматично зливається. Затверджувач SIG Docs повинен залишити коментар /lgtm лише на змінах, які не потребують додаткового технічного огляду.

Затвердження pull requestʼів

Затверджувачі та лідери SIG Docs є єдиними, хто може зливати pull requestʼи в репозиторій вебсайту. Це супроводжується певними обовʼязками.

• Затверджувачі можуть використовувати команду /approve, яка зливає PR в репозиторій.

  Попередження:

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

• Переконайтеся, що запропоновані зміни відповідають посібнику зі змісту документації.

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

• Переконайтеся, що тести Netlify пройшли перед тим, як ви використаєте команду /approve для PR.

  

• Відвідайте попередній перегляд сторінки Netlify для PR, щоб переконатися, що все виглядає добре перед затвердженням.

• Беріть участь у графіку чергування PR Wrangler для щотижневих ротацій. SIG Docs очікує, що всі затверджувачі братимуть участь у цій ротації. Дивіться PR чергування для отримання додаткової інформації.

Як стати затверджувачем

Коли ви відповідаєте вимогам, ви можете стати затверджувачем SIG Docs. Затверджувачі в інших SIG повинні подавати окрему заявку на статус затверджувача в SIG Docs.

Щоб подати заявку:

1. Відкрийте pull request, що додає вас до розділу файлу OWNERS_ALIASES у репозиторії kubernetes/website.

   Примітка:

   Якщо ви не впевнені, де себе додати, додайте себе до `sig-docs-en-owners`.
   

2. Призначте PR одному або кільком поточним затверджувачам SIG Docs.

Якщо заявку схвалено, лідер SIG Docs додає вас до відповідної команди GitHub. Після додавання, @k8s-ci-robot призначає та пропонує вас як рецензента на нові pull request'и.

Що далі

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

6.2 - Відповідальні за PR

SIG Docs затверджувачі беруть участь у тижневих чергуваннях стосовно управління pull request'ами для репозиторію.

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

Обовʼязки

Кожного дня під час тижневого чергування відповідальний за PR:

• Робить огляд відкритих pull request'ів на відповідність стилю та змісту.
  • Почніть з найменших PRʼів (size/XS), і закінчіть найбільшими (size/XXL). Огляньте стільки PRʼів, скільки зможете.
• Переконайтеся, що учасники PR підписали CLA.
  • Використовуйте цей скрипт, щоб нагадати учасникам, які не підписали CLA, зробити це.
• Надання відгуків про зміни та запит технічних оглядів від членів інших SIG.
  • Надання своїх пропозицій щодо запропонованих змін у PR.
  • Якщо вам потрібно перевірити зміст, залиште коментар у PR і запросіть більше деталей.
  • Призначте відповідну мітку(и) sig/.
  • Якщо необхідно, призначте рецензентів з блоку reviewers: у метаданих файлу.
  • Ви також можете позначити SIG для огляду, коментуючи @kubernetes/<sig>-pr-reviews у PR.
• Використовуйте коментар /approve для затвердження PR для злиття. Зливайте PR, коли він готовий.
  • PRʼи повинні мати коментар /lgtm від іншого члена перед злиттям.
  • Розгляньте можливість прийняття технічно правильного змісту, який не відповідає настановам зі стилю. Під час затвердження змін відкрийте новий тікет для розвʼязання питання стилю. Зазвичай такі питання стилю можна описати як гарні перші завдання.
  • Використання виправлень стилю як гарних перших завдань — це хороший спосіб забезпечити наявність легших завдань для допомоги в адаптації нових учасників.
• Також перевіряйте pull requestʼи до коду генератора довідкової документації та оглядайте їх (або залучайте допомогу).
• Підтримуйте відповідального за тікети у розгляді та теґуванні нових тікетів щодня. Дивіться Розгляд та категоризація тікетів для керівництва з використання метаданих SIG Docs.

Корисні запити GitHub для відповідальних

Наступні запити корисні під час роботи з PRʼами. Після обробки цих запитів зазвичай залишається невеликий список PRʼів для огляду. Ці запити виключають PRʼи локалізації. Усі запити стосуються основної гілки, крім останнього.

• Без CLA, не допускається до злиття: Нагадуйте учаснику підписати CLA. Якщо і бот, і людина нагадали їм, закрийте PR і нагадайте їм, що вони можуть відкрити його після підписання CLA. Не оглядайте PRʼи, автори яких не підписали CLA!
• Потребує LGTM: Перелік PRʼів, які потребують LGTM від члена. Якщо PR потребує технічного огляду, залучайте одного з рецензентів, запропонованих ботом. Якщо зміст потребує доопрацювання, додайте пропозиції та відгуки безпосередньо.
• Має LGTM, потребує затвердження документації: Перелік PRʼів, які потребують коментаря /approve для злиття.
• Швидкі виграші: Перелік PRʼів до основної гілки без явних блокувань. (змініть "XS" у розмірі мітки, коли будете працювати з PRʼами [XS, S, M, L, XL, XXL]).
• Не для основної гілки: Якщо PR для гілки dev-, це для майбутнього випуску. Призначте менеджера випуску документації використовуючи: /assign @<github-ім'я_менеджера>. Якщо PR для старої гілки, допоможіть автору визначити кращу гілку.

Корисні команди Prow для відповідальних

# додати мітку англійської мови
/language en

# додати мітку squash до PR, якщо твм більше одного коміту
/label tide/merge-method-squash

# перейменувати PR через Prow (наприклад, робота в процесі [WIP] або кращий опис PR)
/retitle [WIP] <TITLE>

Коли закривати Pull Request'и

Огляди та затвердження є одним з інструментів для утримання нашої черги PR короткою та актуальною. Іншим інструментом є закриття.

Закрийте PRʼи, де:

• Автор не підписав CLA протягом двох тижнів.

  Автори можуть відкрити PR знову після підписання CLA. Це малоризикований спосіб переконатися, що нічого не зливається без підписаного CLA.

• Автор не відповів на коментарі чи відгуки протягом 2 або більше тижнів.

Не бійтеся закривати pull request'и. Учасники можуть легко відкрити знову та продовжити роботу. Часто повідомлення про закриття є тим, що спонукає автора продовжити та завершити свій внесок.

Щоб закрити pull request, залиште коментар /close у PR.

Програма тіньового відповідального за PR

У кінці 2021 року SIG Docs представив PR Wrangler Shadow Program. Програма була введена для допомоги новим учасникам зрозуміти процес управління PR.

Як стати тіньовим відповідальним за PR

• Якщо ви зацікавлені у тому, щоби стати тіньовим відповідальним за PR, будь ласка, відвідайте сторінку Wiki PR Wrangler'ів, щоб побачити графік управління PR на цей рік та зареєструватися.

• Інші можуть звернутися до Slack-каналу #sig-docs для запиту на участь у підтримці відповідальних за PR на конкретний тиждень. Не соромтеся звертатися до Бреда Топола (@bradtopol) або одного зі співголів/лідерів SIG Docs.

• Після реєстрації на підтримку відповідального за PR, представте себе відповідальному за PR у Kubernetes Slack.

6.3 - Відповідальні за тікети

На додаток до PR чергування, офіційні затверджувачі, рецензенти та члени SIG Docs беруть участь у тижневих чергуваннях у розгляді та категоризації тікетів в репозиторії.

Обовʼязки

Кожного дня під час тижневого чергування Відповідальний за тікети буде відповідати за:

• Щоденний розгляд та тегування нових тікетів. Дивіться Розглядв та категоризація тікетів для керівництва з використання метаданих SIG Docs.
• Слідкування за застарілими та "протухлими" тікетами в репозиторії kubernetes/website.
• Підтримку дошки тікетів.

Вимоги

• Повинен бути активним членом організації Kubernetes.
• Мінімум 15 значущих внесків у Kubernetes (з яких певна кількість має бути спрямована на kubernetes/website).
• Виконання ролі неофіційно вже деякий час.

Корисні команди Prow для відповідальних за тікети

Нижче наведені деякі команди, що часто використовуються Відповідальними за тікетами:

# відкрити тікет знов
/reopen

# перенести тікет, що не підходять для k/website до іншого репозиторію
/transfer[-issue]

# змінити стан "протухлих" тікетів
/remove-lifecycle rotten

# змінити стан застарілих тікетів
/remove-lifecycle stale

# призначити sig до тікета
/sig <sig_name>

# додати конкретну область
/area <area_name>

# для тікетів, що підходять для початківців
/good-first-issue

# тікети, що потребують допомоги
/help wanted

# тегування тікетів як підтримки
/kind support

# прийняти розгляду для тікета
/triage accepted

# закрити тікета, з яким ми не будемо працювати і який ще не виправлено
/close not-planned

Щоб знайти більше команд Prow, зверніться до документації Command Help.

Коли закривати тікети

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

Закривайте тікети, коли:

• Схожа проблема повідомляється більше одного разу. Спочатку потрібно позначити її як /triage duplicate; повʼязати її з основним тікетом та потім закрити. Також рекомендується направити користувачів до оригінального тікета.
• Дуже важко зрозуміти та розвʼязати проблему, представлену автором, з наданою інформацією. Однак, заохочуйте користувача надати більше деталей або відкрити питання знову, якщо він зможе відтворити його пізніше.
• Така ж функціональність реалізована деінде. Можна закрити цей тікет та направити користувача в потрібне місце.
• Повідомлена проблема наразі не відповідає цілям проєкту або не планується до розвʼязання.
• Якщо тікет виглядає як спам і явно не стосується теми.
• Якщо проблема повʼязана з зовнішнім обмеженням або залежністю і знаходиться поза контролем проєкту.

Щоб закрити питання, залиште коментар /close на питання.

7 - Cтиль документації

Матеріали цього розділу надають настанови щодо стилю написання, форматування та організації контенту, а також використання налаштувань Hugo, специфічних для документації Kubernetes.

7.1 - Посібник з вмісту документації

Ця сторінка містить вказівки щодо документації Kubernetes.

Якщо у вас є запитання про те, що дозволено, приєднуйтесь до каналу #sig-docs у Kubernetes Slack і запитуйте!

Ви можете зареєструватися на Kubernetes Slack за адресою https://slack.k8s.io/.

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

Огляд

Сирці вебсайту Kubernetes, включаючи документацію, знаходиться в репозиторії kubernetes/website.

Більшість документації Kubernetes знаходиться в теці kubernetes/website/content/<language_code>/docs і специфічна для проєкту Kubernetes.

Що дозволено

Документація Kubernetes дозволяє вміст зі сторонніх проєктів тільки тоді, коли:

• Вміст документує програмне забезпечення в проєкті Kubernetes
• Вміст документує програмне забезпечення, яке знаходиться поза проєктом, але необхідне для функціонування Kubernetes
• Вміст є канонічним на kubernetes.io або посилається на канонічний вміст в іншому місці

Сторонній вміст

Документація Kubernetes включає приклади застосування проєктів у проєкті Kubernetes — проєктів, що знаходяться в організаціях GitHub kubernetes та kubernetes-sigs.

Посилання на активний вміст у проєкті Kubernetes завжди дозволені.

Для функціонування Kubernetes необхідний деякий сторонній вміст. Прикладами є контейнерні середовища (containerd, CRI-O, Docker), мережева політика (втулки CNI), контролери Ingress, та логування.

Документація може посилатися на стороннє програмне забезпечення з відкритим вихідним кодом (OSS) поза проєктом Kubernetes тільки якщо воно необхідне для функціонування Kubernetes.

Контент з подвійним джерелом

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

Контент з подвійним джерелом вимагає вдвічі більше зусиль (або більше!) для підтримки та швидше стає застарілим.

Додаткова інформація

Якщо у вас є запитання про дозволений вміст, приєднуйтесь до каналу #sig-docs у Kubernetes Slack і запитуйте!

Що далі

• Ознайомтесь з посібником зі стилю.

7.2 - Посібник зі стилю документації

Ця сторінка надає вказівки щодо стилю написання документації Kubernetes. Це вказівки, а не правила. Використовуйте здоровий глузд та не соромтеся пропонувати зміни до цього документа за допомогою pull request.

Для отримання додаткової інформації про створення нового вмісту для документації Kubernetes, прочитайте Посібник з вмісту документації.

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

Мова

Документація Kubernetes була перекладена кількома мовами (див. локалізовані файли README).

Процес локалізації документації для інших мови описано в розділіЛокалізація документації Kubernetes.

Документація англійською мовою використовує правопис та граматику американської англійської.

Стандарти форматування документації

Використовуйте UpperCamelCase для обʼєктів API

Коли ви посилаєтеся на взаємодію з обʼєктом API, використовуйте UpperCamelCase, також відомий як Pascal case. Ви можете зустріти інші варіанти написання, наприклад, "configMap", в Довіднику API. У загальній документації краще використовувати UpperCamelCase, називаючи обʼєкт "ConfigMap".

Коли ви загалом обговорюєте обʼєкт API, використовуйте велику літеру тільки на початку речення.

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

Використовуйте кутові дужки для заповнювачів

Використовуйте кутові дужки для заповнювачів. Поясніть читачеві, що представляє заповнювач, наприклад:

Показ інформацію про Pod:

kubectl describe pod <pod-name> -n <namespace>

Якщо простір імен Podʼа є default, ви можете пропустити параметр -n.

Використовуйте жирний шрифт для елементів інтерфейсу користувача

Використовуйте курсив для визначення або введення нових термінів

Використовуйте стиль коду для імен файлів, тек та шляхів

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

Форматування вбудованого коду

Використовуйте кодовий стиль для вбудованого коду та команд

Для вбудованого в документі HTML коду використовуйте теґ <code>. У документі Markdown використовуйте зворотну лапку (`). Проте, API обʼєкти, такі як StatefulSet або ConfigMap, пишуться дослівно (без зворотних лапок); це дозволяє використовувати апострофи для позначення присвійного відмінка.

Використовуйте стиль коду для імен полів обʼєктів та просторів імен

Використовуйте стиль коду для назв команд, інструментів та компонентів Kubernetes

Початок речення з назви інструменту або компонента

Використовуйте загальний дескриптор замість назви компонента

Використовуйте звичайний стиль для значень полів типу string та integer

Для значень полів типу string або integer використовуйте звичайний стиль без лапок.

Однак, розгляньте можливість цитування значень у випадках, коли є ризик, що читачі можуть сплутати значення з типом API.

Посилання на API ресурси Kubernetes

Цей розділ описує, як ми посилаємося на API ресурси в документації.

Уточнення щодо терміна "ресурс"

Kubernetes використовує слово ресурс для позначення ресурсів API. Наприклад, шлях URL /apis/apps/v1/namespaces/default/deployments/my-app представляє Deployment з назвою "my-app" у просторі імен "default". У термінології HTTP, простір імен є ресурсом — так само як всі веб-URL ідентифікують ресурс.

Документація Kubernetes також використовує "ресурс" для опису запитів і обмежень на використання процесорів і памʼяті. Дуже часто доцільно посилатися на API ресурси як на "API ресурси", щоб уникнути плутанини з процесорними ресурсами та ресурсами памʼяті або з іншими видами ресурсів.

Якщо ви використовуєте назву ресурсу в нижньому регістрі у множині, наприклад, deployments або configmaps, надайте додатковий контекст, щоб допомогти читачам зрозуміти, що ви маєте на увазі. Якщо ви використовуєте цей термін у контексті, де також можна використовувати назву в UpperCamelCase, і є ризик неоднозначності, розгляньте можливість використання типу API в UpperCamelCase.

Коли використовувати терміни Kubernetes API

Різні терміни Kubernetes API включають:

• API типи (kind): назви, які використовуються в URL API (такі як pods, namespaces). API типи іноді також називають типами ресурсів.
• API ресурс: одиничні екземпляри API типу (такі як pod, secret).
• Обʼєкт: ресурс, який служить як "запис наміру". Обʼєкт є бажаним станом для конкретної частини вашого кластера, який намагається підтримувати панель управління Kubernetes. Всі обʼєкти в API Kubernetes також є ресурсами.

Для ясності ви можете додати "ресурс" або "обʼєкт", коли посилаєтесь на API ресурс у документації Kubernetes. Наприклад: пишіть "обʼєкт Secret", замість "Secret". Якщо з контексту зрозуміло, що мова йде про ресурс, можна не додавати це слово.

Розгляньте можливість перефразування, коли це допомагає уникнути непорозумінь. Звичайною ситуацією є випадок, коли ви хочете почати речення з API типу, наприклад, "Secret"; оскільки в англійській та інших мовах заголовні літери використовуються на початку речень, читачі не можуть визначити, чи маєте ви на увазі API тип або загальне поняття. Перефразування може допомогти.

Назви API ресурсів

Завжди форматуйте назви API ресурсів, використовуючи UpperCamelCase, також відомий як PascalCase. Не пишіть API типи з використанням форматування коду.

Не розбивайте назву API обʼєкта на окремі слова. Наприклад, використовуйте PodTemplateList, а не Pod Template List.

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

Для отримання додаткової інформації про термінологію Kubernetes API, ознайомтесь із відповідними рекомендаціями щодо Термінології API Kubernetes.

Форматування фрагментів коду

Не включайте символ командного рядка

Відокремлюйте команди від їх виводу

Переконайтеся, що Pod працює на обраному вами вузлі:

kubectl get pods --output=wide

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

NAME     READY     STATUS    RESTARTS   AGE    IP           NODE
nginx    1/1       Running   0          13s    10.200.0.4   worker0

Версіювання прикладів для Kubernetes

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

Якщо інформація є специфічною для версії, версія Kubernetes повинна бути визначена у розділі prerequisites шаблону Task або шаблону Tutorial. Після збереження сторінки, розділ prerequisites буде показаний з назвою — Перед тим, як почати.

Щоб вказати версію Kubernetes для сторінки з завданням або навчальним посібником, включіть min-kubernetes-server-version у front matter сторінки.

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

Наприклад, якщо ви пишете навчальний посібник, що стосується версії Kubernetes 1.8, front matter вашого markdown файлу мають виглядати приблизно так:

---
title: <ваша назва навчального посібника>
min-kubernetes-server-version: v1.8
---

У прикладах коду та конфігурацій не включайте коментарі про альтернативні версії. Будьте обережні, щоб не включати некоректні твердження у ваші приклади у вигляді коментарів, наприклад:

apiVersion: v1 # попередні версії використовують...
kind: Pod
...

Словник Kubernetes.io

Список специфічних для Kubernetes термінів і слів, які слід використовувати послідовно у всьому сайті.

Shortcodes

Hugo Shortcodes допомагають створювати різні рівні риторичної привабливості. Наша документація підтримує три різні Shortcodes в цій категорії: Note {{< note >}}, Caution {{< caution >}} і Warning {{< warning >}}.

1. Оточуйте текст відкриваючим та закриваючим Shortcodeʼом.

2. Використовуйте наступний синтаксис для застосування стилю:

   {{< note >}}
   Немає необхідності включати префікс; Shortcode автоматично додає його. (Note:, Caution:, тощо)
   {{< /note >}}
   

   Вихідний результат:

   Примітка:

   Обраний префікс збігається з текстом теґа.

Note

Використовуйте {{< note >}} для виділення поради або корисної інформації.

Наприклад:

{{< note >}}
Ви _все ще_ можете використовувати Markdown всередині цих Shortcodeʼів.
{{< /note >}}

Вихідний результат:

Ви можете використовувати {{< note >}} у списку:

1. Використовуйте Shortcode примітки у списку

1. Другий пункт з вбудованою приміткою

   {{< note >}}
   Shortcode Warning, Caution і Note, вбудовані у списки, повинні мати відповідний відступ (на рівні початку тексту списку). Див. [Поширені проблеми з Shortcode](#common-shortcode-issues).
   {{< /note >}}

1. Третій пункт у списку

1. Четвертий пункт у списку

Вихідний результат:

1. Використовуйте Shortcode примітки у списку

2. Другий пункт з вбудованою приміткою

   Примітка:

   Шорткоди Warning, Caution і Note, вбудовані у списки, повинні мати відповідний відступ (на рівні початку тексту списку). Див. Поширені проблеми з Shortcode.

3. Третій пункт у списку

4. Четвертий пункт у списку

Caution

Використовуйте {{< caution >}} для привернення уваги до важливої інформації, щоб уникнути помилок.

Наприклад:

{{< caution >}}
Стиль виклику застосовується лише до рядка теґа вище безпосередньо.
{{< /caution >}}

Вихідний результат:

Warning

Використовуйте {{< warning >}} для вказівки на небезпеку або важливу інформацію, яку потрібно обовʼязково враховувати.

Наприклад:

{{< warning >}}
Будьте обережні.
{{< /warning >}}

Вихідний результат:

Поширені проблеми з Shortcode

Нумеровані списки

Shortcode переривають нумеровані списки, якщо не зробити відступ у на рівні початку тексту списку перед сповіщенням та теґом.

Наприклад:

1. Розігрійте духовку до 350˚F

1. Приготуйте тісто та вилийте його у форму.
   {{< note >}}Змастіть форму для кращих результатів.{{< /note >}}

1. Випікайте 20-25 хвилин або до готовності.

Вихідний результат:

1. Розігрійте духовку до 350˚F

2. Приготуйте тісто та вилийте його у форму.

   Примітка:

   Змастіть форму для кращих результатів.

3. Випікайте 20-25 хвилин або до готовності.

Вирази Include

Shortcode всередині include statements зламають збірку. Необхідно вставити їх у батьківський документ до і після виклику include. Наприклад:

{{< note >}}
{{< include "task-tutorial-prereqs.md" >}}
{{< /note >}}

Елементи Markdown

Переноси рядків

Використовуйте один символ переносу рядка (\n) для розділення контенту на рівні блоків, таких як заголовки, списки, зображення, блоки коду тощо. Винятком є заголовки другого рівня, де необхідно зробити два переноси рядка. Заголовки другого рівня слідують після заголовків першого рівня (або заголовка) без передуючих абзаців або тексту. Два переноси рядка допомагають краще візуалізувати загальну структуру контенту в текстовому редакторі.

Ручне перенесення абзаців у вихідному коді Markdown є доречним, оскільки інструмент git та сайт GitHub генерують порівняння файлів на основі рядків. Ручне перенесення довгих рядків допомагає рецензентам легко знаходити зміни у PR і надавати зворотний звʼязок. Це також допомагає командам, які займаються локалізацією, відслідковувати зміни на рівні рядків¹. Перенесення рядка може відбуватися в кінці речення або після знака пунктуації. Винятком є випадки, коли Markdown-посилання або шорткод очікується в одному рядку.

Заголовки та назви

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

Абзаци

Посилання

Списки

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

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

  Примітка:

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

• Використовуйте цифру один з крапкою (1.) для упорядкованих списків.

• Використовуйте (+), (*), або (-) для неупорядкованих списків, але якийсь один з цих символів у одному тексті (уникайте їх змішування)

• Залишайте порожній рядок після кожного списку.

• Відступайте вкладені списки на відповідну кількість пробілів, так щоб сімвол початку елемента спіску був на рівні з початком тексту елемента вищого рівня (наприклад, ⋅⋅⋅).

• Елементи списку можуть складатися з кількох абзаців. Кожен наступний абзац у пункті списку повинен бути відступлений нарівень початку тексту елементу списку або один табулятор.

Таблиці

Семантична мета таблиці — це представлення табличних даних. Користувачі з гарним зором можуть швидко сканувати таблицю, але екранний зчитувач проходить її рядок за рядком. Підпис таблиці використовується для створення описового заголовка для таблиці даних. Допоміжні технології (AT) використовують елемент підпису HTML для таблиці, щоб ідентифікувати вміст таблиці користувачеві в межах структури сторінки.

• Додавайте підписи до таблиць за допомогою shortcodes Hugo для таблиць.

Рекомендації щодо створення контенту

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

Використовуйте теперішній час

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

Використовуйте активний стан

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

Використовуйте просту і пряму мову

Використовуйте просту і пряму мову. Уникайте використання зайвих фраз, наприклад, слова "будь ласка".

Звертайтесь до читача на "ви"

Уникайте латинських фраз

Віддавайте перевагу англійським (місцевим) термінам замість латинських абревіатур.

Виняток: Використовуйте "etc." (et cetera) для позначення "та інше".

Шаблони, яких слід уникати

Уникайте використання "ми"

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

Уникайте жаргону та ідіом

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

Уникайте тверджень про майбутнє

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

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

Уникайте тверджень, які незабаром стануть неактуальними

Уникайте слів таких як "зараз" і "новий". Функція, яка є новою сьогодні, може не вважатися новою через кілька місяців.

Уникайте слів, що припускають певний рівень розуміння

Уникайте слів таких як "просто", "легко", "зрозуміло". Ці слова не додають цінності.

Файл EditorConfig

Проєкт Kubernetes підтримує файл EditorConfig, який встановлює загальні стилістичні уподобання в текстових редакторах, таких як VS Code. Ви можете використовувати цей файл, якщо хочете переконатися, що ваші внески відповідають решті проєкту. Щоб переглянути файл, зверніться до .editorconfig в кореневій теці репозиторію.

Що далі

• Дізнайтеся про написання нової теми.
• Дізнайтеся про використання шаблонів сторінок.
• Дізнайтеся про власні hugo shortcodes.
• Дізнайтеся про створення pull request.

7.3 - Створення діаграм

Цей посібник показує, як створювати, редагувати та поширювати діаграмами за допомогою JavaScript бібліотеки Mermaid. Mermaid.js дозволяє створювати діаграми за допомогою простого синтаксису, подібного до Markdown, всередині Markdown-файлів. Ви також можете використовувати Mermaid для створення файлів зображень у форматі .svg або .png, які ви можете додати до документації.

Цільовою аудиторією цього посібника є будь-хто, хто бажає дізнатися про Mermaid та/або як створювати і додавати діаграми до документації Kubernetes.

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

Схема 1. Теми, які розглядаються в цьому розділі

Все що вам треба для роботи з Mermaid це:

• Знання основ markdown.
• Користуватись онлайн редактором Mermaid.
• Користуватись Hugo shortcodes.
• Користуватись Hugo shortcode {{< figure >}}.
• Виконувати локальний перегляд в Hugo.
• Знати як брати участь у створенні нового контенту.

Чому слід використовувати діаграми в документації

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

Переваги для користувачів включають:

• Приємне перше враження. Детальна текстова сторінка привітання може налякати користувачів, особливо новачків у Kubernetes.
• Швидке освоєння концепцій. Діаграма може допомогти користувачам зрозуміти ключові моменти складної теми. Ваша діаграма може слугувати візуальним навчальним посібником для занурення в деталі теми.
• Краще запамʼятовування. Для деяких легше запамʼятати зображення, ніж текст.

Переваги для учасників включають:

• Допомога у розробці структури та контенту вашого внеску. Наприклад, ви можете почати з простої діаграми, яка охоплює високий рівень, а потім зануритися в деталі.
• Розширення та зростання спільноти користувачів. Зручна для сприйняття документація, доповнена діаграмами, приваблює нових користувачів, які раніше неохоче брали участь у проєкті через уявну складність.

Вам слід враховувати вашу цільову аудиторію. Окрім досвідчених користувачів K8s, у вас буде багато новачків у Kubernetes. Навіть проста діаграма може допомогти новим користувачам засвоїти концепції Kubernetes. Вони стають впевненішими та більш схильними до подальшого дослідження Kubernetes та документації.

Mermaid

Mermaid — це бібліотека JavaScript з відкритим вихідним кодом, яка дозволяє створювати, редагувати та легко ділитися діаграмами, використовуючи простий синтаксис, схожий на Markdown, який використовується в файлах Markdown.

Нижче наведено особливості Mermaid:

• Простий синтаксис коду.
• Включає вебінструмент для кодування та перегляду ваших діаграм.
• Підтримує кілька форматів, включаючи діаграми процесів, станів та послідовностей.
• Легке співробітництво з колегами через URL-адресу для кожної діаграми.
• Широкий вибір форм, ліній, тем та стилів.

Переваги використання Mermaid:

• Немає потреби в спеціальних інструментах для створення діаграм.
• Відповідає поточному робочому процесу з використанням PR. Ви можете розглядати код Mermaid як просто текст Markdown, доданий у ваш PR.
• Простий інструмент створює прості діаграми. Не хочете витрачати час на створення надто складних і деталізованих зображень. Тримайте їх простими!

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

Онлайн редактор

Онлайн редактор Mermaid — це вебінструмент, який дозволяє створювати, редагувати та переглядати діаграми.

Нижче наведено функції редактора:

• Показує код Mermaid разом зі згенерованою діаграмою.
• Генерує URL для кожної збереженої діаграми. URL відображається в адресному рядку вашого оглядача. Ви можете поділитися URL з колегами, які можуть отримати доступ до діаграми та змінювати її.
• Можливість отримати файли .svg або .png.

Методи створення діаграм

На схемі 2 показано три способи створення та додавання діаграм.

Схема 2. Методи створення діаграм.

В тексті

На схемі 3 показано кроки для додавання діаграми за допомогою методу Inline.

Схема 3. Кроки метода inline

Ось перелік кроків, які слід виконати для додавання діаграми за допомогою методу Inline:

1. Створіть вашу діаграму за допомогою онлайн редактора.
2. Збережіть URL діаграми для подальшого доступу.
3. Скопіюйте код Mermaid у місце в вашому файлі .md туди, де ви хочете, щоб зʼявилася діаграма.
4. Додайте підпис під діаграмою, використовуючи текст Markdown.

Під час побудови Hugo виконується код Mermaid і перетворюється на діаграму.

Ось приклад фрагмента коду, що міститься у файлі .md:

---
title: My PR
---
Figure 17 shows a simple A to B process.
some markdown text
...
{{< mermaid >}} 
    graph TB
    A --> B
{{< /mermaid >}}

Figure 17. A to B
more text

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

Нижче наведено переваги методу Inline:

• Використання онлайн редактора.
• Легко копіювати код Mermaid до та з онлайн редактора та вашого файлу .md.
• Відсутність необхідності окремої обробки файлів зображень .svg.
• Текст контенту, код діаграми та підпис до діаграми знаходяться в одному файлі .md.

Ви повинні використовувати локальний та Netlify попередній перегляд для перевірки правильного показу діаграми.

Mermaid+SVG

На схемі 4 показано кроки для додавання діаграми за допомогою методу Mermaid+SVG.

Схема 4. Кроки методу Mermaid+SVG

Нижче наведено кроки, які слід виконати для додавання діаграми за допомогою методу Mermaid+SVG:

1. Створіть діаграму за допомогою онлайн редактора.
2. Збережіть URL діаграми для подальшого доступу.
3. Згенеруйте файл зображення .svg для діаграми та завантажте його до відповідної теки images/.
4. Використовуйте shortcode {{< figure >}} для посилання на діаграму у файлі .md.
5. Додайте підпис за допомогою параметра caption у shortcode {{< figure >}}.

Наприклад, використовуйте онлайн редактор для створення діаграми з назвою boxnet. Збережіть URL діаграми для подальшого доступу. Згенеруйте та завантажте файл boxnet.svg до відповідної теки ../images/.

Використовуйте shortcode {{< figure >}} у файлі .md вашого PR, щоб посилатися на файл зображення .svg та додати підпис.

{{< figure src="/static/images/boxnet.svg" alt="Boxnet figure" class="diagram-large" caption="Figure 14. Boxnet caption" >}}

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

Ви повинні додати URL онлйн редактора як коментар у файлі зображення .svg, використовуючи текстовий редактор. Наприклад, ви б включили наступне на початку файлу зображення .svg:

<!-- Щоб переглянути або редагувати код Mermaid, використовуйте наступний URL: -->
<!-- https://mermaid-js.github.io/mermaid-live-editor/edit/#eyJjb ... <продовження рядка URL> -->

Нижче наведено переваги методу Mermaid+SVG:

• Використання інструменту онлайн редактора.
• Інструмент онлайн редактора підтримує найсучасніший набір функцій Mermaid.
• Використання існуючих методів kubernetes/website для обробки файлів зображень .svg.
• Середовище не вимагає підтримки Mermaid.

Переконайтеся, що ваша діаграма правильно відображається, використовуючи локальний та Netlify попередній перегляд.

Зовнішні інструменти

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

Спочатку створіть діаграму за допомогою зовнішнього інструменту і збережіть її як файл зображення у форматі .svg або .png. Після цього виконайте ті самі кроки, що й у методі Mermaid+SVG для додавання файлів зображень у форматі .svg.

Схема 5. Кроки методу з використання зовнішнього інструменту

Нижче наведено кроки, які слід виконати для додавання діаграми за допомогою методу External Tool:

1. Використовуйте зовнішній інструмент для створення діаграми.
2. Збережіть координати діаграми для доступу інших учасників. Наприклад, ваш інструмент може надати посилання на зображення діаграми, або ви можете зберегти файл з вихідним кодом, такий як .xml, у публічному репозиторії для подальшого доступу інших учасників.
3. Згенеруйте та збережіть діаграму у вигляді файлу зображення .svg або .png. Завантажте цей файл у відповідну теку ../images/.
4. Використовуйте shortcode {{< figure >}} для посилання на діаграму у файлі .md.
5. Додайте підпис за допомогою параметра caption у shortcode {{< figure >}}.

Ось приклад використання shortcode {{< figure >}} для діаграми images/apple.svg:

{{< figure src="/static/images/apple.svg" alt="red-apple-figure" class="diagram-large" caption="Figure 9. A Big Red Apple" >}}

Якщо ваш зовнішній інструмент малювання дозволяє:

• Ви можете включати кілька логотипів .svg або .png, іконок та зображень у свою діаграму. Однак, переконайтеся, що ви дотримуєтеся авторських прав і дотримуєтесь керівництва Kubernetes щодо використання контенту третіх сторін.
• Ви повинні зберегти координати діаграми для подальшого доступу інших учасників. Наприклад, ваш інструмент може надати посилання на зображення діаграми, або ви можете зберегти файл з вихідним кодом, наприклад .xml, для доступу інших учасників.

Для отримання додаткової інформації про логотипи та зображення K8s і CNCF, зверніться до розділу CNCF Artwork.

Нижче наведено переваги методу External Tool:

• Учасники добре знайомі з зовнішнім інструментом.
• Діаграми потребують більше деталей, ніж може надати Mermaid.

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

Приклади

У цьому розділі показано декілька прикладів діаграм Mermaid.

Приклад 1 — Обмеження на поширення топології Podʼів

Схема 6 показує діаграму зі сторінки Обмеження на поширення топології Podʼів

Схема 6. Обмеження поширення топології Podʼів

Код:

graph TB
   subgraph "zoneB"
       n3(Node3)
       n4(Node4)
   end
   subgraph "zoneA"
       n1(Node1)
       n2(Node2)
   end
 
   classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
   classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
   classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
   class n1,n2,n3,n4 k8s;
   class zoneA,zoneB cluster;

Приклад 2 – Ingress

Схема 7 показує діаграму, що зʼявляється на сторінці Що таке Ingress.

Code block:

graph LR;
 client([client])-. Ingress-managed <br> load balancer .->ingress[Ingress];
 ingress-->|routing rule|service[Service];
 subgraph cluster
 ingress;
 service-->pod1[Pod];
 service-->pod2[Pod];
 end
 classDef plain fill:#ddd,stroke:#fff,stroke-width:4px,color:#000;
 classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff;
 classDef cluster fill:#fff,stroke:#bbb,stroke-width:2px,color:#326ce5;
 class ingress,service,pod1,pod2 k8s;
 class client plain;
 class cluster cluster;

Приклад 3 — Потік системи К8s

На схемі 8 зображено Mermaid-діаграму послідовності, яка показує системний потік між компонентами K8 для запуску контейнера.

Код:

%%{init:{"theme":"neutral"}}%%
sequenceDiagram
    actor me
    participant apiSrv as control plane<br><br>api-server
    participant etcd as control plane<br><br>etcd datastore
    participant cntrlMgr as control plane<br><br>controller<br>manager
    participant sched as control plane<br><br>scheduler
    participant kubelet as node<br><br>kubelet
    participant container as node<br><br>container<br>runtime
    me->>apiSrv: 1. kubectl create -f pod.yaml
    apiSrv-->>etcd: 2. save new state
    cntrlMgr->>apiSrv: 3. check for changes
    sched->>apiSrv: 4. watch for unassigned pods(s)
    apiSrv->>sched: 5. notify about pod w nodename=" "
    sched->>apiSrv: 6. assign pod to node
    apiSrv-->>etcd: 7. save new state
    kubelet->>apiSrv: 8. look for newly assigned pod(s)
    apiSrv->>kubelet: 9. bind pod to node
    kubelet->>container: 10. start container
    kubelet->>apiSrv: 11. update pod status
    apiSrv-->>etcd: 12. save new state

Ви можете стилізувати один або декілька елементів діаграми за допомогою CSS. Це досягається за допомогою двох типів операторів у коді Mermaid.

• classDef визначає клас атрибутів стилю.
• class визначає один або декілька елементів, до яких буде застосовано клас.

В коді до схеми 7 ви можете побачити приклад.

classDef k8s fill:#326ce5,stroke:#fff,stroke-width:4px,color:#fff; // визначає стиль для класу k8s
class ingress,service,pod1,pod2 k8s; // Клас k8s застосовується до елементів ingress, service, pod1 та pod2.

Ви можете включити один або декілька операторів classDef та class у вашу діаграму. Ви також можете використовувати офіційний шістнадцятковий код кольору K8s #326ce5 для компонентів K8s у вашій діаграмі.

Для отримання додаткової інформації про стилізацію та класи див. Mermaid Styling and classes docs.

Як використовувати підписи до діаграм

Підпис — це короткий опис діаграми. Підпис може містити назву або короткий опис діаграми. Підписи не замінюють пояснювальний текст у вашій документації, а радше слугують як "контекстний звʼязок" між цим текстом та вашою діаграмою.

Поєднання тексту та діаграми, повʼязаних разом за допомогою підпису, допомагає надати чітке уявлення про інформацію, яку ви хочете донести до користувача.

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

На схемі 9 показано три компоненти правильного використання підписів: діаграма, підпис до діаграми та посилання на діаграму в тексті.

Схема 9. Компоненти заголовків

Діаграма

Методи Mermaid+SVG та External Tool генерують файли зображень у форматі .svg.

Існує shortcode {{< figure >}} для діаграми, що знаходиться у файлі зображення .svg, збереженому в /images/docs/components-of-kubernetes.svg:

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 4. Компоненти архітектури Kubernetes" >}}

Ви повинні передавати значення src, alt, class та caption у shortcode {{< figure >}}. Ви можете змінювати розмір діаграми, використовуючи класи diagram-large, diagram-medium та diagram-small.

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

Підпис до діаграми

Далі додайте підпис до діаграми.

Якщо ви використовуєте діаграму з файла зображення .svg, вам слід використовувати параметр caption shortcodeʼа {{< figure >}}.

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 4. Компоненти архітектури Kubernetes" >}}

Якщо ви використовуєте діаграму, що є вбудованим кодом Mermaid, тоді слід використовувати текст Markdown.

Схема 4. Компоненти архітектури Kubernetes

Нижче наведено кілька аспектів, які слід враховувати при додаванні підписів до діаграм:

• Використовуйте shortcode {{< figure >}} для додавання підпису до діаграм, створених за допомогою методів Mermaid+SVG та External Tool.
• Використовуйте простий текст Markdown для додавання підпису до діаграм, створених за допомогою методу Inline.
• Перед підписом діаграми додайте Схема НОМЕР.. Ви повинні використовувати слово Схема, і номер повинен бути унікальним для кожної діаграми на вашій сторінці документації. Додайте крапку після номера.
• Додайте текст підпису діаграми після Схема НОМЕР. в тому ж рядку. Підпис повинен закінчуватися крапкою. Зберігайте текст підпису коротким.
• Розташовуйте підпис до діаграми ПІД вашою діаграмою.

Посилання на діаграму

Нарешті, ви можете додати посилання на діаграму. Воно використовується у вашому тексті та повинно передувати самій діаграмі. Це дозволяє користувачеві повʼязати ваш текст із відповідною діаграмою. Схема НОМЕР у вашому посиланні та підписі повинні співпадати.

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

Ось приклад посилання на діаграму:

Схема 10 зображує компоненти архітектури Kubernetes.
Панель управління ...

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

Повна картина

Схема 10 показує діаграму архітектури Kubernetes, яка включає діаграму, підпис до діаграми та посилання на діаграму. Shortcode {{< figure >}} показує діаграму, додає підпис і включає необовʼязковий параметр link, щоб ви могли мати гіперпосилання на діаграму. Посилання на діаграму знаходиться в цьому абзаці.

Ось shortcode {{< figure >}} для цієї діаграми:

{{< figure src="/images/docs/components-of-kubernetes.svg" alt="Kubernetes pod running inside a cluster" class="diagram-large" caption="Схема 10. Архітектура Kubernetes." link="/docs/concepts/overview/components/" >}}

Поради

• Завжди використовуйте оналйн редактор для створення/редагування вашої діаграми.

• Завжди використовуйте локальний Hugo та попередній перегляд Netlify, щоб перевірити, як діаграма відображається в документації.

• Включайте джерела діаграм, такі як URL, місцезнаходження вихідного коду або вказуйте, що код є самодокументуючим.

• Завжди використовуйте підписи до діаграм.

• Дуже корисно включати зображення діаграми у форматі .svg або .png та/або вихідний код Mermaid у тікетах та PRs.

• Для методів Mermaid+SVG та External Tool використовуйте файли зображень .svg, оскільки вони залишаються чіткими при збільшенні діаграми.

• Найкраща практика для файлів .svg — завантажити їх в інструмент для редагування SVG та використати функцію "Конвертувати текст у криві". Це гарантує, що діаграма відображатиметься однаково на всіх системах, незалежно від доступності шрифтів і підтримки рендерингу шрифтів.

• Mermaid не підтримує додаткові іконки або зображень.

• Shortcodes Hugo Mermaid не працюють в оналайн редакторі.

• Кожного разу, коли ви змінюєте діаграму в оналайн редакторі, ви повинні зберегти її, щоб згенерувати новий URL для діаграми.

• Натисніть на діаграми в цьому розділі, щоб переглянути код і відображення діаграми в оналайн редакторі.

• Перегляньте вихідний код цієї сторінки, diagram-guide.md, для отримання додаткових прикладів.

• Ознайомтеся з документацією Mermaid, щоб отримати пояснення та приклади.

Найважливіше — Робіть діаграми простими. Це заощадить час вам і вашим колегам-учасникам, а також полегшить читання для нових та досвідчених користувачів.

7.4 - Написання нової теми

Ця сторінка показує, як створити нову тему для документації Kubernetes.

Перш ніж ви розпочнете

Створіть форк репозиторію документації Kubernetes, як описано в розділі Створення PR.

Вибір типу сторінки

Перед тим, як почати писати нову тему, подумайте про тип сторінки, який найкраще підходить для вашого контенту:

Створення нової сторінки

Використовуйте тип контенту для кожної нової сторінки, яку ви пишете. Сайт документації надає шаблони або Hugo archetypes для створення нових сторінок контенту. Щоб створити нову сторінку, запустіть команду hugo new з шляхом до файлу, який ви хочете створити. Наприклад:

hugo new docs/concepts/my-first-concept.md

Вибір заголовка та імені файлу

Виберіть заголовок, який містить ключові слова, за якими ви хочете, щоб пошукові системи знаходили вашу сторінку. Створіть імʼя файлу, використовуючи слова в заголовку, розділені дефісами. Наприклад, тема з заголовком Використання HTTP-проксі для доступу до API Kubernetes має імʼя файлу http-proxy-access-api.md. Вам не потрібно додавати слово "kubernetes" в імʼя файлу, оскільки "kubernetes" вже є в URL для теми, наприклад:

/docs/tasks/extend-kubernetes/http-proxy-access-api/

Додавання заголовка теми до метаданих front matter

У вашій темі додайте поле title до метаданих. Метадані — це блок YAML, який знаходиться між потрійними рисками на початку сторінки. Ось приклад:

---
title: Використання HTTP-проксі для доступу до API Kubernetes
---

Вибір теки

Залежно від типу сторінки, розмістіть ваш новий файл у підтеці однієї з тек:

• /content/en/docs/tasks/
• /content/en/docs/tutorials/
• /content/en/docs/concepts/

Ви можете розмістити свій файл у наявній підтеці або створити нову підтекуг.

Розміщення вашої теми в таблиці змісту

Таблиця змісту створюється динамічно, використовуючи структуру тек вихідного коду документації. Теки верхнього рівня у /content/en/docs/ створюють навігацію верхнього рівня, а підтеки мають власні записи в таблиці змісту.

Кожна підтека має файл _index.md, який представляє "домашню" сторінку для контенту даної підтеки. _index.md не потребує шаблону. Він може містити оглядовий контент про теми в теці.

Інші файли в теці зазвичай сортуються в алфавітному порядку. Це майже ніколи не є найкращим випадком. Щоб контролювати відносне сортування тем у підтеці, встановіть в ключ метаданих weight: значення, ціле число. Зазвичай ми використовуємо кратні 10, щоб врахувати додавання тем пізніше. Наприклад, тема з вагою 10 буде розташована перед темою з вагою 20.

Вбудовування коду у вашу тему

Якщо ви хочете включити якийсь код у вашу тему, ви можете вбудувати код безпосередньо у файл, використовуючи синтаксис блоку коду markdown. Це рекомендується в таких випадках (не вичерпний список):

• Код показує вивід з команди, наприклад kubectl get deploy mydeployment -o json | jq '.status'.
• Код недостатньо загальний для того, щоб користувачі могли його випробувати. Наприклад, ви можете вбудувати YAML файл для створення Pod, який залежить від конкретної реалізації FlexVolume.
• Код є неповним прикладом, оскільки його мета — підкреслити частину великого файлу. Наприклад, при описі способів налаштування RoleBinding, ви можете надати короткий фрагмент безпосередньо у вашому файлі теми.
• Код не призначений для того, щоб користувачі його випробовували з інших причин. Наприклад, коли ви описуєте, як новий атрибут має бути доданий до ресурсу за допомогою команди kubectl edit, ви можете надати короткий приклад, який містить лише атрибут для додавання.

Включення коду з іншого файлу

Інший спосіб включити код у вашу тему — створити новий, повний зразок файлу (або групи зразків файлів), а потім посилатися на зразок із вашої теми. Використовуйте цей метод для включення зразків YAML файлів, коли зразок є загальним і багаторазовим, і ви хочете, щоб читач спробував його самостійно.

При додаванні нового самостійного зразка файлу, такого як YAML файл, розмістіть код в одній з підтек <LANG>/examples/, де <LANG> — це мова для теми. У файлі вашої теми використовуйте shortcode code_sample:

{{% code_sample file="<RELPATH>/my-example-yaml>" %}}

де <RELPATH> — це шлях до файлу, який потрібно включити, відносно теки examples. Наступний shortcode Hugo посилається на YAML файл, розташований за адресою /content/en/examples/pods/storage/gce-volume.yaml.

{{% code_sample file="pods/storage/gce-volume.yaml" %}}

Показ як створити обʼєкт API з файлу конфігурації

Якщо вам потрібно продемонструвати, як створити обʼєкт API на основі файлу конфігурації, розмістіть файл конфігурації в одній з підтек у <LANG>/examples.

У вашій темі вкажіть цю команду:

kubectl create -f https://k8s.io/examples/pods/storage/gce-volume.yaml

Для прикладу теми, яка використовує цей прийом, див. Запуск Stateful застосунку в одному екземплярі.

Додавання зображень до теми

Розмістіть файли зображень у теці /images. Переважний формат зображення — SVG.

Що далі

• Дізнайтеся про використання типів контенту сторінок.
• Дізнайтеся про створення pull request.

7.5 - Типи контенту сторінок

Документація Kubernetes містить кілька типів контенту сторінок:

• Concept (Концепт)
• Task (Завдання)
• Tutorial (Посібник)
• Reference (Довідка)

Розділи контенту

Кожен тип контенту сторінок містить кілька розділів, визначених коментарями Markdown і HTML-заголовками. Ви можете додати заголовки контенту до вашої сторінки за допомогою shortcode heading. Коментарі та заголовки допомагають підтримувати структуру типів контенту сторінок.

Приклади коментарів Markdown, що визначають розділи контенту сторінки:

<!-- overview -->

<!-- body -->

Щоб створити загальні заголовки на ваших контентних сторінках, використовуйте body heading із рядком заголовка.

Приклади рядків заголовків:

• whatsnext (що далі)
• prerequisites (вимоги)
• objectives (цілі)
• cleanup (очищення)
• synopsis (синопсис)
• seealso (див. також)
• options (параметри)

Наприклад, щоб створити заголовок whatsnext, додайте shortcode із рядком "whatsnext":

## {{% heading "whatsnext" %}}

Щоб створити заголовок prerequisites, скористайтеся таким shortcode:

## {{% heading "prerequisites" %}}

Shortcode heading очікує один строковий параметр. Рядок заголовка відповідає префіксу змінної у файлах i18n/<lang>.toml. Наприклад:

i18n/en.toml:

[whatsnext_heading]
other = "What's next"

i18n/ko.toml:

[whatsnext_heading]
other = "다음 내용"

Типи контенту

Кожен тип контенту неформально визначає свою очікувану структуру сторінки. Створюйте контент сторінки, використовуючи рекомендовані розділи сторінок.

Концепт

Сторінка концепту пояснює певний аспект Kubernetes. Наприклад, сторінка концепту може описувати обʼєкт Kubernetes Deployment і пояснювати його роль як застосунку під час розгортання, масштабування та оновлення. Зазвичай сторінки концептів не містять послідовностей кроків, а натомість надають посилання на завдання або посібники.

Щоб написати нову сторінку концепту, створіть файл Markdown у підтеці content/en/docs/concepts з такими характеристиками:

Сторінки концептів поділяються на три розділи:

Розділи overview і body зʼявляються як коментарі на сторінці концепту. Ви можете додати розділ whatsnext на вашу сторінку за допомогою shortcode heading.

Заповніть кожен розділ контентом. Дотримуйтесь цих вказівок:

• Організуйте контент за допомогою заголовків H2 і H3.
• Для розділу overview задайте контекст теми одним абзацом.
• У розділі body поясніть концепцію.
• Для розділу whatsnext надайте список із кількох пунктів для подальшого вивчення теми.

Приклад опублікованої сторінки концепту: Анотації.

Завдання

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

Щоб написати нову сторінку завдання, створіть файл Markdown у підтеці /content/en/docs/tasks з такими характеристиками:

Розділи overview, steps і discussion зʼявляються як коментарі на сторінці завдання. Ви можете додати розділи prerequisites і whatsnext на вашу сторінку за допомогою shortcode heading.

У кожному розділі напишіть ваш контент, використовуючи такі вказівки:

• Використовуйте мінімум заголовків H2 (з двома символами # на початку). Самі розділи мають заголовки, які автоматично додаються шаблоном.
• У розділі overview використовуйте абзац для встановлення контексту для всієї теми.
• У розділі prerequisites використовуйте списки з пунктами, де це можливо. Додаткові вимоги додавайте під include. Стандартні вимоги включають працюючий кластер Kubernetes.
• У розділі steps використовуйте пронумеровані списки.
• У розділі discussion використовуйте звичайний контент для розширення інформації, про яку йдеться у розділі steps.
• У розділі whatsnext надайте список із кількох тем, які можуть зацікавити читача далі.

Приклад опублікованої сторінки завдання: Використання HTTP-проксі для доступу до API Kubernetes.

Посібник

Сторінка посібника показує, як досягти мети, яка є більшою, ніж одне завдання. Зазвичай сторінка посібника містить кілька розділів, кожен із яких має послідовність кроків. Наприклад, посібник може містити покроковий огляд зразка коду, що ілюструє певну функцію Kubernetes. Посібники можуть включати поверхневі пояснення, але повинні посилатися на повʼязані концептуальні теми для глибоких пояснень.

Щоб написати нову сторінку посібника, створіть файл Markdown у підтеці /content/en/docs/tutorials з такими характеристиками:

Розділи overview, objectives і lessoncontent зʼявляються як коментарі на сторінці посібника. Ви можете додати розділи prerequisites, cleanup і whatsnext на вашу сторінку за допомогою shortcode heading.

У кожному розділі напишіть ваш контент, використовуючи такі вказівки:

• Використовуйте мінімум заголовків H2 (з двома символами # на початку). Самі розділи мають заголовки, які автоматично додаються шаблоном.
• У розділі overview використовуйте абзац для встановлення контексту для всієї теми.
• У розділі prerequisites використовуйте списки з пунктами, де це можливо. Додаткові вимоги додавайте під include.
• У розділі objectives використовуйте списки з пунктами.
• У розділі lessoncontent використовуйте комбінацію пронумерованих списків і наративного контенту, де це доречно.
• У розділі cleanup використовуйте пронумеровані списки для опису кроків, необхідних для очищення стану кластера після завершення завдання.
• У розділі whatsnext надайте список із кількох тем, які можуть зацікавити читача далі.

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

Довідка

Сторінка довідки інструмента компонента показує опис і параметри прапорців для інструмента компонента Kubernetes. Кожна сторінка генерується зі скриптів із використанням команд інструмента компонента.

Сторінка довідки з інструмента має кілька можливих розділів:

Приклади опублікованих сторінок довідки з інструмента:

• kubeadm init
• kube-apiserver
• kubectl

Що далі

• Дізнайтеся про настанови зі стилю
• Дізнайтеся про настанови з контенту
• Дізнайтеся про організацію контенту

7.6 - Організація контенту

Цей сайт використовує Hugo. В Hugo організація контенту є основним концептом.

Списки сторінок

Порядок сторінок

Бічне меню документації, оглядач сторінок документації тощо формуються за допомогою стандартного порядку сортування Hugo, який сортує за вагою (починаючи з 1), датою (новіші перші), і нарешті за заголовком посилання.

Щоб перемістити сторінку або розділ вверх, задайте вагу у front matter сторінки:

title: My Page
weight: 10

Основне меню документації

Основне меню Документація формується з розділів, що знаходяться в docs/, з прапорцем main_menu, встановленим у front matter файлу контенту _index.md:

main_menu: true

Зверніть увагу, що заголовок посилання береться з linkTitle сторінки, тому, якщо ви хочете, щоб він був відмінним від заголовка, змініть його у файлі контенту:

main_menu: true
title: Page Title
linkTitle: Title used in links

Бічне меню документації

Бічне меню документації формується з поточного дерева розділів в docs/.

Воно відображатиме всі розділи та їх сторінки.

Якщо ви не хочете відображати розділ або сторінку, встановіть прапорець toc_hide в значення true у front matter:

toc_hide: true

Коли ви переходите до розділу, який має контент, показується конкретний розділ або сторінка (наприклад, _index.md). Інакше показується перша сторінка всередині цього розділу.

Оглядач сторінок документації

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

Якщо ви не хочете відображати розділ або сторінку, встановіть прапорець toc_hide в значення true у front matter:

toc_hide: true

Основне меню

Посилання сайту в меню у верхньому правому куті, а також у нижньому колонтитулі, формуються за допомогою перегляду сторінок. Це робиться для того, щоб переконатися, що сторінка дійсно існує. Тому, якщо розділ case-studies не існує на сайті (для мови), він не буде показаний.

Пакети сторінок

Окрім окремих контентних сторінок (файли Markdown), Hugo підтримує Пакети сторінок.

Один приклад — Custom Hugo Shortcodes. Це вважається leaf bundle. Все, що знаходиться нижче теки, включаючи index.md, буде частиною пакета. Це також включає посилання, що є відносними до сторінки, зображення, які можна обробити тощо:

en/docs/home/contribute/includes
├── example1.md
├── example2.md
├── index.md
└── podtemplate.json

Ще один широко використовуваний приклад — пакет includes. Він встановлює headless: true у front matter, що означає, що він не отримує власний URL. Він використовується тільки в інших сторінках.

en/includes
├── default-storage-class-prereqs.md
├── index.md
├── partner-script.js
├── partner-style.css
├── task-tutorial-prereqs.md
├── user-guide-content-moved.md
└── user-guide-migration-notice.md

Декілька важливих приміток до файлів у пакетах:

• Для перекладених пакетів будь-які відсутні не контентні файли будуть успадковані з мов, що знаходяться вище. Це запобігає дублюванню.
• Усі файли в пакеті є тим, що Hugo називає Resources, і ви можете надавати метадані для кожної мови, такі як параметри і заголовок, навіть якщо це не підтримує front matter (YAML файли тощо). Див. Метадані ресурсів сторінок.
• Значення, яке ви отримуєте з .RelPermalink Resource є відносним до сторінки. Див. Permalinks.

Стилі

Джерело стилів SASS для цього сайту зберігається у assets/sass і автоматично будується Hugo.

Що далі

• Дізнайтеся про власні shortcodes Hugo
• Дізнайтеся про настанови зі стилю
• Дізнайтеся про настанови з контенту

7.7 - Власні shortcodes Hugo

Ця сторінка пояснює, як використовувати shortcodes Hugo в документації Markdown для Kubernetes.

Детальніше про shortcodes можна дізнатися в документації Hugo.

Стан функції

На сторінці Markdown (.md файл) на цьому сайті ви можете додати shortcodes для відображення версії та стану документованої функції.

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

Нижче наведено демонстрацію фрагмента стану функції, який відображає функцію як стабільну в останній версії Kubernetes.

{{< feature-state state="stable" >}}

Показується як:

Дійсні значення для state:

• alpha
• beta
• deprecated
• stable

Код стану функції

Показана версія Kubernetes типово є версією сторінки або сайту. Ви можете змінити версію стану функції, передавши параметр for_k8s_version для shortcode. Наприклад:

{{< feature-state for_k8s_version="v1.10" state="beta" >}}

Показується як:

Отримання стану функції з файлу опису

Щоб динамічно визначити стан функції, використовуйте параметр feature_gate_name. Деталі стану функції будуть витягнуті з відповідного файлу опису функціональних можливостей розташованого в content/en/docs/reference/command-line-tools-reference/feature-gates/. Наприклад:

{{< feature-state feature_gate_name="NodeSwap" >}}

Показується як:

Опис функціональних можливостей

На сторінці Markdown (.md файл) на цьому сайті ви можете додати код для показу опису функціональної можливості.

Демонстрація опису функціональної можливості

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

{{< feature-gate-description name="DryRun" >}}

Показується як:

DryRun: Вмикає запити dry rin на боці сервера, щоб можна було тестувати валідацію, злиття та мутацію без впровадження змін.

Глосарій

Існують два коротких коди для глосарія: glossary_tooltip та glossary_definition.

Ви можете посилатися на терміни глосарія з включенням, яке автоматично оновлюється і замінює вміст відповідними посиланнями з нашого глосарія. Коли вказівник миші знаходиться над терміном з глосарія, опис терміна з глосарія відобразиться у вигляді підказки. Термін глосарія також відображається як посилання.

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

Дані для термінів глосарія зберігаються в теці глосарія, з файлом вмісту для кожного терміна глосарія.

Демонстрація глосарія

Наприклад, наступне включення в Markdown показується для терміна кластер з підказкою:

{{< glossary_tooltip text="cluster" term_id="cluster" >}}

Ось коротке визначення глосарія:

{{< glossary_definition prepend="Кластер — " term_id="cluster" length="short" >}}

яке показується як:

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

Ви також можете включити повне визначення:

{{< glossary_definition term_id="cluster" length="all" >}}

яке показується як:

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

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

Посилання на довідник API

Ви можете створити посилання на сторінку довідника API Kubernetes, використовуючи короткий код api-reference, наприклад, на довідник Pod:

{{< api-reference page="workload-resources/pod-v1" >}}

Вміст параметра page є суфіксом URL сторінки довідника API.

Ви можете посилатися на конкретне місце на сторінці, вказавши параметр anchor, наприклад, на довідник PodSpec або розділ environment-variables сторінки:

{{< api-reference page="workload-resources/pod-v1" anchor="PodSpec" >}}
{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" >}}

Ви можете змінити текст посилання, вказавши параметр text, наприклад, посилаючись на Змінні оточення розділ сторінки:

{{< api-reference page="workload-resources/pod-v1" anchor="environment-variables" text="Змінні оточення" >}}

Заголовки таблиць

Ви можете зробити таблиці більш доступними для екранних зчитувачів, додавши заголовок таблиці. Щоб додати заголовок до таблиці, оберніть таблицю кодом table і вкажіть заголовок за допомогою параметра caption.

Ось приклад:

{{< table caption="Configuration parameters" >}}
Parameter | Description | Default
:---------|:------------|:-------
`timeout` | The timeout for requests | `30s`
`logLevel` | The log level for log output | `INFO`
{{< /table >}}

Показується як:

Якщо ви переглянете HTML для таблиці, ви повинні побачити цей елемент одразу після відкриваючого елемента <table>:

<caption style="display: none;">Configuration parameters</caption>

Вкладки

На сторінці Markdown (.md файл) на цьому сайті ви можете додати набір вкладок для показу різних варіантів рішення.

Короткий код tabs приймає такі параметри:

• name: Ім’я, яке відображається на вкладці.
• codelang: Якщо ви надаєте внутрішній вміст для короткого коду tab, ви можете вказати Hugo, яку мову коду використовувати для підсвічування.
• include: Файл для включення у вкладку. Якщо вкладка знаходиться в Hugo leaf bundle, файл, який може бути будь-якого MIME типу, підтримуваного Hugo, шукається у самому пакеті. Якщо ні, сторінка вмісту, яку потрібно включити, шукається відносно поточної сторінки. Зверніть увагу, що з include у вас немає внутрішнього вмісту shortcode і ви повинні використовувати синтаксис самозакриваючих теґів. Наприклад, {{< tab name="Content File #1" include="example1" />}}. Мову потрібно вказати у codelang, або мова буде визначена на основі імені файлу. Ффайли non-content стандартно підсвічуються як код.
• Якщо ваш внутрішній вміст є Markdown, ви повинні використовувати роздільник % для оточення вкладки. Наприклад, {{% tab name="Tab 1" %}}This is **markdown**{{% /tab %}}
• Ви можете комбінувати зазначені вище варіації всередині набору вкладок.

Нижче наведено демонстрацію shortcode вкладок.

Демонстрація вкладок: Підсвічування коду

{{< tabs name="tab_with_code" >}}
{{< tab name="Tab 1" codelang="bash" >}}
echo "This is tab 1."
{{< /tab >}}
{{< tab name="Tab 2" codelang="go" >}}
println "This is tab 2."
{{< /tab >}}
{{< /tabs >}}

Показується як:

• Tab 1
• Tab 2

echo "This is tab 1."

println "This is tab 2."

Демонстрація вкладок: Вбудований Markdown та HTML

{{< tabs name="tab_with_md" >}}
{{% tab name="Markdown" %}}
This is **some markdown.**
{{< note >}}
It can even contain shortcodes.
{{< /note >}}
{{% /tab %}}
{{< tab name="HTML" >}}
<div>
	<h3>Plain HTML</h3>
	<p>This is some <i>plain</i> HTML.</p>
</div>
{{< /tab >}}
{{< /tabs >}}

Показується як:

• Markdown
• HTML

Демонстрація вкладок: Включення файлів

{{< tabs name="tab_with_file_include" >}}
{{< tab name="Content File #1" include="example1" />}}
{{< tab name="Content File #2" include="example2" />}}
{{< tab name="JSON File" include="podtemplate" />}}
{{< /tabs >}}

Показується як:

• Content File #1
• Content File #2
• JSON File

{
    "apiVersion": "v1",
    "kind": "PodTemplate",
    "metadata": {
      "name": "nginx"
    },
    "template": {
      "metadata": {
        "labels": {
          "name": "nginx"
        },
        "generateName": "nginx-"
      },
      "spec": {
         "containers": [{
           "name": "nginx",
           "image": "dockerfile/nginx",
           "ports": [{"containerPort": 80}]
         }]
      }
    }
  }

Файли вихідного коду

Ви можете використовувати код {{% code_sample %}} для вбудовування вмісту файлу в кодовий блок, щоб користувачі могли завантажити або скопіювати його вміст у буфер обміну. Цей код використовується, коли вміст зразкового файлу є загальним і багаторазовим, і ви хочете, щоб користувачі могли спробувати його самостійно.

Цей короткий код приймає два іменованих параметри: language та file. Обов’язковий параметр file використовується для вказання шляху до файлу, який відображається. Опційний параметр language використовується для вказання мови програмування файлу. Якщо параметр language не надано, код намагатиметься вгадати мову на основі розширення файлу.

Наприклад:

{{% code_sample language="yaml" file="application/deployment-scale.yaml" %}}

Вихідний результат:

application/deployment-scale.yaml

apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
spec:
  selector:
    matchLabels:
      app: nginx
  replicas: 4 # Update the replicas from 2 to 4
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.16.1
        ports:
        - containerPort: 80

Коли ви додаєте новий зразковий файл, наприклад YAML файл, створіть файл в одній з підтек <LANG>/examples/, де <LANG> — це мова для сторінки. У Markdown вашої сторінки використовуйте код code:

{{% code_sample file="<RELATIVE-PATH>/example-yaml>" %}}

де <RELATIVE-PATH> — шлях до зразкового файлу, який потрібно включити, відносно теки examples. Наступний код посилається на YAML файл, розташований за адресою /content/en/examples/configmap/configmaps.yaml.

{{% code_sample file="configmap/configmaps.yaml" %}}

Застарілий код {{% codenew %}} замінюється на {{% code_sample %}}. Використовуйте {{% code_sample %}} (а не {{% codenew %}} чи {{% code %}}) у новій документації.

Маркер контенту третіх сторін

Для роботи з Kubernetes потрібно стороннє програмне забезпечення. Наприклад, вам зазвичай потрібно додати DNS-сервер до вашого кластера, щоб забезпечити правильну роботу розпізнавання імен.

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

Використання цих shortcodes додає відмову від відповідальності до будь-якої сторінки документації, яка їх використовує.

Списки

Для списку кількох сторонніх елементів додайте:

{{% thirdparty-content %}}

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

Елементи

Якщо у вас є список, в якому більшість елементів належать до програмного забезпечення проєкту (наприклад: сам Kubernetes, і окремий компонент Descheduler), то є інша форма для використання.

Додайте короткий код:

{{% thirdparty-content single="true" %}}

перед елементом або відразу після заголовка для конкретного елемента.

Деталі

Ви можете відобразити HTML елемент <details> за допомогою шорткоду:

{{< details summary="Детальніше про віджети" >}}
API розширення frobnicator реалізує _віджети_ із використанням тексту прикладу.

Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
{{< /details >}}

Це буде показано так:

Рядки версій

Щоб створити рядок версії для включення в документацію, ви можете вибрати з кількох shortcode для версії. Кожен код версії відображає рядок версії, отриманий зі значення параметра версії, знайденого у файлі конфігурації сайту, hugo.toml. Два найбільш часто використовуваних параметри версії — це latest і version.

{{< param "version" >}}

Код {{< param "version" >}} генерує значення поточної версії документації Kubernetes з параметра сайту version. Код param приймає назву одного параметра сайту, в цьому випадку: version.

Показується як:

{{< latest-version >}}

Код {{< latest-version >}} повертає значення параметра сайту latest. Параметр сайту latest оновлюється, коли випускається нова версія документації. Цей параметр не завжди відповідає значенню version у наборі документації.

Показується як:

{{< latest-semver >}}

Короткий код {{< latest-semver >}} генерує значення latest без префікса "v".

Показується як:

{{< version-check >}}

Код {{< version-check >}} перевіряє, чи присутній параметр min-kubernetes-server-version на сторінці, а потім використовує це значення для порівняння з version.

Показується як:

{{< latest-release-notes >}}

Код {{< latest-release-notes >}} генерує рядок версії з latest і видаляє префікс "v". Короткий код друкує нове посилання на сторінку з нотатками про випуски з модифікованим рядком версії.

Показується як:

Що далі

• Дізнайтеся про Hugo.
• Дізнайтеся про створення нової теми.
• Дізнайтеся про типи вмісту сторінок.
• Дізнайтеся про відкриття pull request.
• Дізнайтеся про розширений варіант участі.

8 - Оновлення довідкової документації

Тематика цього розділу описує, як генерувати довідники Kubernetes.

Щоб створити довідкову документацію, ознайомтесь з наступним посібником:

• Швидкий старт для генерації довідкової документації

8.1 - Швидкий старт з довідковою документацією

Ця сторінка показує, як використовувати скрипт update-imported-docs.py для генерації довідкової документації Kubernetes. Скрипт автоматизує налаштування збірки та генерує довідкову документацію для релізу.

Перш ніж ви розпочнете

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS.

• Вам потрібно встановити ці інструменти:

  • Python версії v3.7.x+
  • Git
  • Golang версії 1.13+
  • Pip для встановлення PyYAML
  • PyYAML версії v5.1.2
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для довідки по команді kubectl)

• Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

• Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Отримання репозиторію документації

Переконайтеся, що ваш форк репозиторію website синхронізований з віддаленим репозиторієм kubernetes/website на GitHub (гілка main), і клонуйте ваш форк website собі локально.

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

Визначте базову теку вашого клону. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — github.com/website. Наступні кроки посилаються на вашу базову теку як <web-base>.

Огляд update-imported-docs

Скрипт update-imported-docs.py розташований у теці <web-base>/update-imported-docs/.

Скрипт будує наступні довідки:

• Довідкові сторінки компонентів та інструментів
• Довідка по команді kubectl
• Довідка по API Kubernetes

Скрипт update-imported-docs.py генерує довідкову документацію Kubernetes з вихідного коду Kubernetes. Скрипт створює тимчасову теку в /tmp на вашій машині та клонує потрібні репозиторії: kubernetes/kubernetes та kubernetes-sigs/reference-docs у цю теку. Скрипт встановлює вашу змінну середовища GOPATH на цю тимчасову теку. Встановлюються три додаткові змінні середовища:

• K8S_RELEASE
• K8S_ROOT
• K8S_WEBROOT

Скрипт потребує два аргументи для успішного виконання:

• YAML конфігураційний файл (reference.yml)
• Версія релізу, наприклад: 1.17

Конфігураційний файл містить поле generate-command. Поле generate-command визначає серію інструкцій для збірки з kubernetes-sigs/reference-docs/Makefile. Змінна K8S_RELEASE визначає версію релізу.

Скрипт update-imported-docs.py виконує наступні кроки:

1. Клонування повʼязаних репозиторіїв, зазначених у конфігураційному файлі. Для генерації довідкових документів типово клонуються kubernetes-sigs/reference-docs.
2. Запуск команд під час клонування репозиторіїв для підготовки генератора документації та генерація HTML і Markdown файлів.
3. Копіювання згенерованих HTML і Markdown файлів до локального клону репозиторію <web-base> за вказаними в конфігураційному файлі шляхами.
4. Оновлення посилань команд kubectl з kubectl.md у секції в довідці по команді kubectl.

Коли згенеровані файли знаходяться у вашому локальному клоні репозиторію <web-base>, ви можете подати їх у pull request до <web-base>.

Формат конфігураційного файлу

Кожен конфігураційний файл може містити кілька репозиторіїв, які будуть імпортовані разом. За необхідності, ви можете налаштувати конфігураційний файл, редагуючи його вручну. Можна створювати нові конфігураційні файли для імпорту інших груп документів. Ось приклад YAML конфігураційного файлу:

repos:
- name: community
  remote: https://github.com/kubernetes/community.git
  branch: master
  files:
  - src: contributors/devel/README.md
    dst: docs/imported/community/devel.md
  - src: contributors/guide/README.md
    dst: docs/imported/community/guide.md

Окремі Markdown документи, імпортовані за допомогою інструмента, повинні відповідати Посібнику зі стилю документації.

Налаштування reference.yml

Відкрийте <web-base>/update-imported-docs/reference.yml для редагування. Не змінюйте вміст поля generate-command, якщо не розумієте, як команда використовується для побудови довідок. Оновлення reference.yml зазвичай не потрібне. Іноді зміни в upstream вихідному коді можуть вимагати змін у конфігураційному файлі (наприклад: залежності версій golang та зміни сторонніх бібліотек). Якщо ви стикаєтеся з проблемами збірки, зверніться до команди SIG-Docs у #sig-docs Kubernetes Slack.

У reference.yml, files містить список полів src та dst. Поле src містить розташування згенерованого Markdown файлу у теці збірки kubernetes-sigs/reference-docs, а поле dst визначає, куди скопіювати цей файл у клонованому репозиторії kubernetes/website. Наприклад:

repos:
- name: reference-docs
  remote: https://github.com/kubernetes-sigs/reference-docs.git
  files:
  - src: gen-compdocs/build/kube-apiserver.md
    dst: content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
  ...

Зверніть увагу, що коли є багато файлів для копіювання з одного джерела в одну й ту ж теку призначення, ви можете використовувати шаблони в значенні src. Ви повинні надати назву теки як значення для dst. Наприклад:

  files:
  - src: gen-compdocs/build/kubeadm*.md
    dst: content/en/docs/reference/setup-tools/kubeadm/generated/

Запуск інструмента update-imported-docs

Ви можете запустити інструмент update-imported-docs.py наступним чином:

cd <web-base>/update-imported-docs
./update-imported-docs.py <configuration-file.yml> <release-version>

Наприклад:

./update-imported-docs.py reference.yml 1.17

Виправлення посилань

Конфігураційний файл release.yml містить інструкції для виправлення відносних посилань. Щоб виправити відносні посилання у ваших імпортованих файлах, встановіть властивість gen-absolute-links на true. Ви можете знайти приклад цього в release.yml.

Додавання та коміт змін у репо kubernetes/website

Перегляньте файли, що були згенеровані та скопійовані до <web-base>:

cd <web-base>
git status

Вивід показує нові та змінені файли. Згенеровані результати варіюються залежно від змін, внесених у upstream вихідний код.

Згенеровані файли компонентів інструментів

content/en/docs/reference/command-line-tools-reference/cloud-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-apiserver.md
content/en/docs/reference/command-line-tools-reference/kube-controller-manager.md
content/en/docs/reference/command-line-tools-reference/kube-proxy.md
content/en/docs/reference/command-line-tools-reference/kube-scheduler.md
content/en/docs/reference/setup-tools/kubeadm/generated/kubeadm.md
content/en/docs/reference/kubectl/kubectl.md

Згенеровані файли довідки команди kubectl

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js
static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/css/font-awesome.min.css

Згенеровані теки та файли довідки по Kubernetes API

static/docs/reference/generated/kubernetes-api/v1.31/index.html
static/docs/reference/generated/kubernetes-api/v1.31/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.31/js/scroll.js
static/docs/reference/generated/kubernetes-api/v1.31/js/query.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.31/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.31/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.31/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.31/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.woff2

Виконайте git add та git commit, щоб зафіксувати файли.

Створення pull request

Створіть pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

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

Що далі

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

• Генерація довідкової документації для компонентів і інструментів Kubernetes
• Генерація довідкової документації для команд kubectl
• Генерація довідкової документації для API Kubernetes

8.2 - Внесок у код Kubernetes

Ця сторінка показує, як зробити внесок у проєкт kubernetes/kubernetes. Ви можете виправити помилки, знайдені в документації API Kubernetes або вмісті компонентів Kubernetes, таких як kubeadm, kube-apiserver та kube-controller-manager.

Якщо ви хочете відновити довідкову документацію для API Kubernetes або компонентів kube-* з коду upstream, перегляньте наступні інструкції:

• Генерація довідкової документації для API Kubernetes
• Генерація довідкової документації для компонентів і інструментів Kubernetes

Перш ніж ви розпочнете

• Вам потрібно встановити наступні інструменти:

  • Git
  • Golang версії 1.13+
  • Docker
  • etcd
  • make
  • gcc compiler/linker

• Ваша змінна середовища GOPATH повинна бути встановлена, а розташування etcd повинно бути у вашій змінній середовища PATH.

• Вам потрібно знати, як створити pull request у репозиторій GitHub. Зазвичай це включає створення форку репозиторію. Для отримання додаткової інформації дивіться Створення Pull Request та Стандартний Workflow Fork & Pull Request на GitHub.

Загальна картина

Довідкова документація для API Kubernetes та компонентів kube-*, таких як kube-apiserver, kube-controller-manager, автоматично генерується з вихідного коду в upstream Kubernetes.

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

Клонування репозиторію Kubernetes

Якщо ви ще не маєте репозиторію kubernetes/kubernetes, отримайте його зараз:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Визначте базову теку вашого клону репозиторію kubernetes/kubernetes. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — $GOPATH/src/github.com/kubernetes/kubernetes. Наступні кроки посилаються на вашу базову теку як <k8s-base>.

Визначте базову теку вашого клону репозиторію kubernetes-sigs/reference-docs. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Наступні кроки посилаються на ваш базовий каталог як <rdocs-base>.

Редагування вихідного коду Kubernetes

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

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

Зробіть зміни у вихідному коді upstream

Ось приклад редагування коментаря у вихідному коді Kubernetes.

У вашому локальному репозиторії kubernetes/kubernetes, перейдіть на основну гілку і переконайтеся, що вона оновлена:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Припустимо, що у цьому вихідному файлі в основній гілці є помилка "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

У вашому локальному середовищі відкрийте types.go і змініть "atmost" на "at most".

Перевірте, що ви змінили файл:

git status

Вивід показує, що ви в основній гілці та що вихідний файл types.go був змінений:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Збережіть відредагований файл

Виконайте git add і git commit, щоб зберегти зміни, які ви внесли до цього моменту. У наступному кроці ви зробите другий коміт. Важливо зберігати ваші зміни в окремих комітах.

Генерація OpenAPI специфікації та супутніх файлів

Перейдіть до <k8s-base> і запустіть ці скрипти:

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Виконайте git status, щоб побачити, що було згенеровано.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Перегляньте вміст api/openapi-spec/swagger.json, щоб переконатися, що помилка виправлена. Наприклад, ви можете виконати git diff -a api/openapi-spec/swagger.json. Це важливо, оскільки swagger.json є вхідними даними для другого етапу процесу генерації документації.

Виконайте git add і git commit, щоб зберегти ваші зміни. Тепер у вас є два коміти: один з відредагованим файлом types.go, і один, що містить згенеровану OpenAPI специфікацію та супутні файли. Залишить ці два коміти окремо. Тобто, не зливайте ваші коміти.

Подайте свої зміни як pull request до основної гілки репозиторію kubernetes/kubernetes. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request, поки він не буде злитий.

PR 57758 є прикладом pull request, який виправляє помилку в коді Kubernetes.

Cherry-pick вашого коміту у релізну гілку

У попередньому розділі ви відредагували файл в основній гілці та потім запустили скрипти для генерації OpenAPI специфікації та супутніх файлів. Потім ви подали свої зміни у pull request до основної гілки репозиторію kubernetes/kubernetes. Тепер припустимо, що ви хочете повернути вашу зміну в релізну гілку. Наприклад, якщо основна гілка використовується для розробки версії Kubernetes 1.31, і ви хочете повернути вашу зміну у гілку release-1.30.

Згадайте, що ваш pull request має два коміти: один для редагування types.go і один для файлів, згенерованих скриптами. Наступний крок — запропонувати cherry pick вашого першого коміту у гілку release-1.30. Ідея полягає в тому, щоб зробити cherry-pick коміту, що редагував types.go, але не коміту, що має результати запуску скриптів. Для інструкцій дивіться Запропонувати Cherry Pick.

Коли у вас є pull request для cherry-pick вашого коміту у гілку release-1.30, наступний крок — запустити ці скрипти в гілці release-1.30 у вашому локальному середовищі.

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Тепер додайте коміт до вашого cherry-pick pull request, що містить нещодавно згенеровану OpenAPI специфікацію та супутні файли. Слідкуйте за вашим pull request, поки він не буде злитий у гілку release-1.30.

На цьому етапі й основна гілка, й гілка release-1.30 містять ваш оновлений файл types.go та набір згенерованих файлів, що відображають зміну, яку ви внесли в types.go. Зазначте, що згенерована OpenAPI специфікація та інші згенеровані файли в гілці release-1.30 не обовʼязково будуть такими ж, як згенеровані файли в основній гілці. Згенеровані файли в гілці release-1.30 містять API елементи лише з Kubernetes 1.30. Згенеровані файли в основній гілці можуть містити API елементи, які не є в 1.30, але розробляються для 1.31.

Генерація опублікованих довідкових документів

Попередній розділ показав, як редагувати вихідний файл і потім згенерувати декілька файлів, включаючи api/openapi-spec/swagger.json у репозиторії kubernetes/kubernetes. Файл swagger.json є файлом визначення OpenAPI, який використовується для генерації документації API.

Тепер ви готові слідувати посібнику Генерація довідкової документації для API Kubernetes, щоб згенерувати опубліковану довідкову документацію API Kubernetes.

Що далі

• Генерація довідкової документації для API Kubernetes
• Генерація довідкових документів для компонентів і інструментів Kubernetes
• Генерація довідкової документації для команд kubectl

8.3 - Генерація документації для API Kubernetes

Ця сторінка демонструє, як оновити документацію API Kubernetes.

Документація API Kubernetes формується на основі специфікації OpenAPI Kubernetes з використанням коду генерації з kubernetes-sigs/reference-docs.

Якщо ви знайшли помилки у згенерованій документації, вам потрібно виправити їх на upstream.

Якщо вам потрібно тільки згенерувати документацію з OpenAPI, продовжте читати цю сторінку.

Перш ніж ви розпочнете

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS.

• Вам потрібно встановити ці інструменти:

  • Python версії v3.7.x+
  • Git
  • Golang версії 1.13+
  • Pip для встановлення PyYAML
  • PyYAML версії v5.1.2
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для довідки по команді kubectl)

• Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

• Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Налаштування локальних репозиторіїв

Створіть локальне робоче середовище і встановіть ваш GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Отримайте локальну копію наступних репозиторіїв:

go get -u github.com/kubernetes-sigs/reference-docs

go get -u github.com/go-openapi/loads
go get -u github.com/go-openapi/spec

Якщо у вас ще немає репозиторію kubernetes/website, отримайте його зараз:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Отримайте копію репозиторію kubernetes/kubernetes як k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

• Основна тека вашої копії kubernetes/kubernetes репозиторію є $GOPATH/src/k8s.io/kubernetes. Подальші кроки використовують цю основну директорію як <k8s-base>.

• Основна тека вашої копії kubernetes/website репозиторію є $GOPATH/src/github.com/<your username>/website. Подальші кроки використовують цю основну директорію як <web-base>.

• Основна тека вашої копії kubernetes-sigs/reference-docs репозиторію є $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Подальші кроки використовують цю основну директорію як <rdocs-base>.

Генерація документації API

Цей розділ демонструє, як згенерувати опубліковану документацію API Kubernetes.

Встановлення змінних для зборки

• Встановіть K8S_ROOT на <k8s-base>.
• Встановіть K8S_WEBROOT на <web-base>.
• Встановіть K8S_RELEASE на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.17.0, встановіть K8S_RELEASE на 1.17.0.

Наприклад:

export K8S_WEBROOT=${GOPATH}/src/github.com/<your-username>/website
export K8S_ROOT=${GOPATH}/src/k8s.io/kubernetes
export K8S_RELEASE=1.17.0

Створення теки версії та завантаження специфікації Open API

Ціль збірки updateapispec створює теку версії для збірки. Після створення теки, специфікація Open API завантажується з репозиторію <k8s-base>. Ці кроки забезпечують відповідність версій конфігураційних файлів і Kubernetes Open API специфікації з версією релізу. Назва теки версії слідує шаблону v<major>_<minor>.

У теці <rdocs-base>, виконайте наступну ціль збірки:

cd <rdocs-base>
make updateapispec

Збірка документації API

Ціль copyapi будує документацію API та копіює згенеровані файли до теки у <web-base>. Виконайте наступну команду у <rdocs-base>:

cd <rdocs-base>
make copyapi

Перевірте, що ці два файли були згенеровані:

[ -e "<rdocs-base>/gen-apidocs/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-apidocs/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Перейдіть до основної теки вашого локального <web-base>, і перегляньте, які файли були змінені:

cd <web-base>
git status

Вихідний результат буде подібним до:

static/docs/reference/generated/kubernetes-api/v1.31/css/bootstrap.min.css
static/docs/reference/generated/kubernetes-api/v1.31/css/font-awesome.min.css
static/docs/reference/generated/kubernetes-api/v1.31/css/stylesheet.css
static/docs/reference/generated/kubernetes-api/v1.31/fonts/FontAwesome.otf
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.eot
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.svg
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.ttf
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.woff
static/docs/reference/generated/kubernetes-api/v1.31/fonts/fontawesome-webfont.woff2
static/docs/reference/generated/kubernetes-api/v1.31/index.html
static/docs/reference/generated/kubernetes-api/v1.31/js/jquery.scrollTo.min.js
static/docs/reference/generated/kubernetes-api/v1.31/js/navData.js
static/docs/reference/generated/kubernetes-api/v1.31/js/scroll.js

Оновлення індексних сторінок документації API

При генерації документації для нового релізу, оновіть файл <web-base>/content/en/docs/reference/kubernetes-api/api-index.md з новим номером версії.

• Відкрийте <web-base>/content/en/docs/reference/kubernetes-api/api-index.md для редагування, і оновіть номер версії документації API. Наприклад:

  ---
  title: v1.17
  ---
  
  [Kubernetes API v1.17](/docs/reference/generated/kubernetes-api/v1.17/)
  

• Відкрийте <web-base>/content/en/docs/reference/_index.md для редагування, і додайте нове посилання на найновішу документацію API. Видаліть найстаріше посилання на версію документації API. Має бути пʼять посилань на найновіші версії документації API.

Локальне тестування документації API

Опублікуйте локальну версію документації API. Перевірте локальний попередній перегляд.

cd <web-base>
git submodule update --init --recursive --depth 1 # якщо ще не зроблено
make container-serve

Коміт змін

У <web-base>, виконайте git add і git commit, щоб зафіксувати зміни.

Подайте ваші зміни як pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request, і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

Що далі

• Швидкий старт з генерації документації
• Генерація документації для компонентів та інструментів Kubernetes
• Генерація документації для команд kubectl

8.4 - Генерація документації для команд kubectl

Ця сторінка показує, як згенерувати довідкову документацію для команд kubectl.

Перш ніж ви розпочнете

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS.

• Вам потрібно встановити ці інструменти:

  • Python версії v3.7.x+
  • Git
  • Golang версії 1.13+
  • Pip для встановлення PyYAML
  • PyYAML версії v5.1.2
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для довідки по команді kubectl)

• Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

• Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Налаштування локальних репозиторіїв

Створіть локальне робоче середовище і встановіть ваш GOPATH:

mkdir -p $HOME/<workspace>

export GOPATH=$HOME/<workspace>

Отримайте локальну копію наступних репозиторіїв:

go get -u github.com/spf13/pflag
go get -u github.com/spf13/cobra
go get -u gopkg.in/yaml.v2
go get -u github.com/kubernetes-sigs/reference-docs

Якщо у вас ще немає репозиторію kubernetes/website, отримайте його зараз:

git clone https://github.com/<your-username>/website $GOPATH/src/github.com/<your-username>/website

Отримайте копію репозиторію kubernetes/kubernetes як k8s.io/kubernetes:

git clone https://github.com/kubernetes/kubernetes $GOPATH/src/k8s.io/kubernetes

Видаліть пакет spf13 з $GOPATH/src/k8s.io/kubernetes/vendor/github.com:

rm -rf $GOPATH/src/k8s.io/kubernetes/vendor/github.com/spf13

Репозиторій kubernetes/kubernetes надає вихідний код kubectl і kustomize.

• Визначте основну теку вашої копії репозиторію kubernetes/kubernetes. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша основна тека є $GOPATH/src/k8s.io/kubernetes. Подальші кроки використовують цю основну теку як <k8s-base>.

• Визначте основну теку вашої копії репозиторію kubernetes/website. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша основна тека є $GOPATH/src/github.com/<your-username>/website. Подальші кроки використовують цю основну теку як <web-base>.

• Визначте основну теку вашої копії kubernetes-sigs/reference-docs репозиторію. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша основна тека є $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Подальші кроки використовують цю основну теку як <rdocs-base>.

У вашій локальній копії k8s.io/kubernetes перевірте гілку інтересу і переконайтеся, що вона актуальна. Наприклад, якщо ви хочете згенерувати документацію для Kubernetes 1.30.0, ви можете використати ці команди:

cd <k8s-base>
git checkout v1.30.0
git pull https://github.com/kubernetes/kubernetes 1.30.0

Якщо вам не потрібно редагувати вихідний код kubectl, дотримуйтесь інструкцій для Налаштування змінних для зборки.

Редагування вихідного коду kubectl

Документація довідки для команд kubectl автоматично генерується з вихідного коду kubectl. Якщо ви хочете змінити довідкову документацію, перший крок — змінити один або кілька коментарів у вихідному коді kubectl. Змініть їх у вашій локальній копії репозиторію kubernetes/kubernetes, а потім подайте pull request до основної гілки github.com/kubernetes/kubernetes.

PR 56673 є прикладом pull requestг, який виправляє помилку в вихідному коді kubectl.

Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів. Продовжуйте слідкувати за вашим pull request до його злиття в цільову гілку репозиторію kubernetes/kubernetes.

Cherry pick вашої зміни до релізної гілки

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

Наприклад, припустимо, що основна гілка використовується для розробки Kubernetes 1.31 і ви хочете повернути вашу зміну до релізної гілки release-1.30. Для інструкцій про те, як це зробити, дивіться Пропонування вибірки.

Слідкуйте за вашим запитом на вибірку до його злиття в релізну гілку.

Налаштування змінних для збірки

Перейдіть до <rdocs-base>. У командному рядку встановіть наступні змінні середовища.

• Встановіть K8S_ROOT на <k8s-base>.
• Встановіть K8S_WEBROOT на <web-base>.
• Встановіть K8S_RELEASE на версію документації, яку ви хочете зібрати. Наприклад, якщо ви хочете зібрати документацію для Kubernetes 1.30, встановіть K8S_RELEASE на 1.30.

Наприклад:

export K8S_WEBROOT=$GOPATH/src/github.com/<your-username>/website
export K8S_ROOT=$GOPATH/src/k8s.io/kubernetes
export K8S_RELEASE=1.30

Створення теки версії

Ціль збірки createversiondirs створює версійну теку і копіює конфігураційні файли довідки для kubectl до теки версії. Назва теки версії слідує шаблону v<major>_<minor>.

У теці <rdocs-base> виконайте наступну ціль зборки:

cd <rdocs-base>
make createversiondirs

Перевірте теґ релізу у k8s.io/kubernetes

У вашій локальній копії <k8s-base> перевірте гілку, яка містить версію Kubernetes, яку ви хочете задокументувати. Наприклад, якщо ви хочете згенерувати документацію для Kubernetes 1.30.0, перевірте теґ v1.30. Переконайтеся, що ваша локальна гілка актуальна.

cd <k8s-base>
git checkout v1.30.0
git pull https://github.com/kubernetes/kubernetes v1.30.0

Запустіть код генерації документації

У вашій локальній копії <rdocs-base>, виконайте ціль зборки copycli. Команда запускається як root:

cd <rdocs-base>
make copycli

Команда copycli очищує тимчасову теку збірки, генерує файли команд kubectl і копіює зведену HTML-сторінку довідки команд kubectl та активи до <web-base>.

Знайдіть згенеровані файли

Перевірте, чи ці два файли були згенеровані:

[ -e "<rdocs-base>/gen-kubectldocs/generators/build/index.html" ] && echo "index.html built" || echo "no index.html"
[ -e "<rdocs-base>/gen-kubectldocs/generators/build/navData.js" ] && echo "navData.js built" || echo "no navData.js"

Знайдіть скопійовані файли

Перевірте, чи всі згенеровані файли були скопійовані до вашої <web-base> теки:

cd <web-base>
git status

Вивід має включати змінені файли:

static/docs/reference/generated/kubectl/kubectl-commands.html
static/docs/reference/generated/kubectl/navData.js

Вивід також може включати:

static/docs/reference/generated/kubectl/scroll.js
static/docs/reference/generated/kubectl/stylesheet.css
static/docs/reference/generated/kubectl/tabvisibility.js
static/docs/reference/generated/kubectl/node_modules/bootstrap/dist/css/bootstrap.min.css
static/docs/reference/generated/kubectl/node_modules/highlight.js/styles/default.css
static/docs/reference/generated/kubectl/node_modules/jquery.scrollto/jquery.scrollTo.min.js
static/docs/reference/generated/kubectl/node_modules/jquery/dist/jquery.min.js
static/docs/reference/generated/kubectl/node_modules/font-awesome/css/font-awesome.min.css

Локально протестуйте документацію

Побудуйте документацію Kubernetes у вашій локальній копії <web-base>.

cd <web-base>
git submodule update --init --recursive --depth 1 # якщо не було зроблено раніше
make container-serve

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

Додайте та зафіксуйте зміни в kubernetes/website

Запустіть git add та git commit, щоб зафіксувати файли.

Створіть pull request

Створіть pull request до репозиторію kubernetes/website. Слідкуйте за вашим pull request і відповідайте на коментарі рецензентів за потреби. Продовжуйте слідкувати за вашим pull request до його злиття.

Через кілька хвилин після злиття вашого pull request оновлені теми довідки стануть видимими в опублікованій документації.

Що далі

• Швидкий старт генерування довідкової документації
• Генерація довідкової документації для компонентів і інструментів Kubernetes
• Генерація довідкової документації для API Kubernetes

8.5 - Генерація довідкової документації для метрик

Ця сторінка демонструє, як згенерувати довідкову документацію для метрик.

Перш ніж ви розпочнете

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS.

• Вам потрібно встановити ці інструменти:

  • Python версії v3.7.x+
  • Git
  • Golang версії 1.13+
  • Pip для встановлення PyYAML
  • PyYAML версії v5.1.2
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для довідки по команді kubectl)

• Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

• Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

Клонування репозиторію Kubernetes

Генерація документації для метрик відбувається в репозиторії Kubernetes. Щоб клонувати репозиторій, перейдіть до теки, де ви хочете, щоб знаходилася клонована копія.

Потім виконайте наступну команду:

git clone https://www.github.com/kubernetes/kubernetes 

Це створить теку kubernetes у вашій поточній робочій теці.

Генерація документації для метрик

У клонованому репозиторії Kubernetes знайдіть теку test/instrumentation/documentation. Документація для метрик генерується в цій теці.

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

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

./test/instrumentation/update-documentation.sh

Щоб перевірити наявність змін, виконайте команду:

git status

Вивід буде схожий на:

./test/instrumentation/documentation/documentation.md
./test/instrumentation/documentation/documentation-list.yaml

Скопіюйте згенерований файл документації для метрик в репозиторій вебсайту Kubernetes

1. Встановіть змінну середовища для кореневої теки вебсайту Kubernetes.

   Виконайте наступну команду, щоб встановити кореневу теку вебсайту:

   export WEBSITE_ROOT=<шлях до кореня вебсайту>
   

2. Скопіюйте згенерований файл метрик в репозиторій вебсайту Kubernetes.

   cp ./test/instrumentation/documentation/documentation.md "${WEBSITE_ROOT}/content/en/docs/reference/instrumentation/metrics.md"
   

   Примітка:

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

Створіть pull request

Щоб створити pull request, дотримуйтесь інструкцій у розділі Відкриття pull request.

Що далі

• Внесок у код Kubernetes
• Генерація довідкової документації для компонентів і інструментів Kubernetes
• Генерація довідкової документації для команд kubectl

8.6 - Генерація довідкових сторінок для компонентів та інструментів Kubernetes

Ця сторінка показує, як створювати довідкові сторінки для компонентів та інструментів Kubernetes.

Перш ніж ви розпочнете

Розпочніть з розділу Передумови у довідковому посібнику Quickstart для генерування документації.

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

Що далі

• Довідковий посібник Quickstart для генерування документації
• Генерація довідкової документації для команд kubectl
• Генерація довідкової документації для API Kubernetes
• Внесення змін до проєкту Kubernetes для документації

8.7 -

Вимоги:

• Вам потрібна машина, що працює під управлінням Linux або macOS.

• Вам потрібно встановити ці інструменти:

  • Python версії v3.7.x+
  • Git
  • Golang версії 1.13+
  • Pip для встановлення PyYAML
  • PyYAML версії v5.1.2
  • make
  • gcc компілятор/лінкер
  • Docker (Потрібен тільки для довідки по команді kubectl)

• Ваша змінна середовища PATH повинна включати необхідні інструменти для збірки, такі як бінарники Go та python.

• Вам потрібно знати, як створити pull request до репозиторію на GitHub. Це включає створення власного форку репозиторію. Для отримання додаткової інформації дивіться Робота з локальним клоном.

9 - Розширена участь

Ця сторінка передбачає, що ви вже знаєте, як додавати новий контент та перевіряти роботу інших, і готові дізнатися більше про способи участі. Вам потрібно використовувати командний рядок Git та інші інструменти для виконання деяких з цих завдань.

Пропонування покращень

Члени SIG Docs можуть пропонувати покращення.

Після того, як ви вже деякий час вносите зміни в документацію Kubernetes, у вас можуть зʼявитися ідеї щодо покращення настанов зі стилю, настанов з контенту, інструментів, які використовуються для створення документації, стилю вебсайту, процесів перевірки та злиття pull request-ів, або інших аспектів документації. Для забезпечення максимальної прозорості ці пропозиції повинні обговорюватися на зустрічі SIG Docs або у списку розсилки kubernetes-sig-docs. Крім того, корисно мати певний контекст щодо того, як все зараз працює і чому в минулому були прийняті певні рішення, перш ніж пропонувати кардинальні зміни. Найшвидший спосіб отримати відповіді на запитання про те, як працює документація, — запитати в каналі #sig-docs на kubernetes.slack.com.

Після того, як обговорення відбулося, і SIG Docs погодився щодо бажаного результату, ви можете працювати над запропонованими змінами найбільш відповідним чином. Наприклад, оновлення керівництва зі стилю або функціональності вебсайту може включати відкриття pull request, тоді як зміна, повʼязана з тестуванням документації, може передбачати співпрацю з sig-testing.

Координація документації для випуску Kubernetes

Затверджувачі SIG Docs можуть координувати документацію для випуску Kubernetes.

Кожен випуск Kubernetes координується командою, яка бере участь у робочій групі (SIG) sig-release. Серед інших членів команди випуску: загальний керівник випуску, а також представники sig-testing та інші. Щоб дізнатися більше про процеси випуску Kubernetes, зверніться до https://github.com/kubernetes/sig-release.

Представник SIG Docs для даного випуску координує наступні завдання:

• Моніторинг електронної таблиці для відстеження функцій щодо нових або змінених функцій, які впливають на документацію. Якщо документація для певної функції не буде готова до випуску, ця функція може не бути включена у випуск.
• Регулярне відвідування зустрічей sig-release та надання оновлень про статус документації для випуску.
• Перегляд та редагування документації для функцій, підготовлених SIG, відповідальним за реалізацію функції.
• Злиття pull request-ів, повʼязаних з випуском, і підтримка гілки Git для випуску.
• Наставництво інших учасників SIG Docs, які хочуть навчитися виконувати цю роль у майбутньому. Це називається "shadowing".
• Публікація змін у документації, повʼязаних з випуском, коли публікуються артефакти випуску.

Координація випуску зазвичай займає 3-4 місяці, і цей обовʼязок передається між затверджувачами SIG Docs.

Виконання обовʼязків New Contributor Ambassador

Затверджувачі SIG Docs можуть бути New Contributor Ambassador.

Помічники для нових учасників вітають нових учасників SIG-Docs, пропонують PRʼи новим учасникам та наставляють нових учасників через їх перші кілька PR-ів.

ОбовʼязкиNew Contributor Ambassador включають:

• Моніторинг каналу #sig-docs Slack на предмет запитань від нових учасників.
• Співпраця з керівниками PRʼів для ідентифікації good first issues для нових учасників.
• Наставництво нових учасників через їхні перші кілька PRʼів до репозиторію документації.
• Допомога новим учасникам у створенні складніших PRʼів, необхідних їм для того, щоб стати членами Kubernetes.
• Поручительство за учасників на їхньому шляху до членства у Kubernetes.
• Проведення щомісячної зустрічі для допомоги та наставництва нових учасників.

Поточні Амбасадори нових учасників оголошуються на кожній зустрічі SIG-Docs та в каналі #sig-docs Kubernetes.

Поручительство за нового учасника

Рецензенти SIG Docs можуть бути поручителями нових учасників.

Після того, як новий учасник успішно подав 5 значних pull requestʼів до одного або кількох репозиторіїв Kubernetes, він має право подати заявку на членство в організації Kubernetes. Членство учасника повинно бути підтримано двома поручителями, які вже є рецензентами.

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

Виконання обовʼязків співголови SIG

Члени SIG Docs можуть бути співголовою SIG Docs.

Вимоги

Член Kubernetes повинен відповідати наступним вимогам для того, щоб бути співголовою:

• Розуміти робочі процеси та інструментарій SIG Docs: git, Hugo, локалізація, блог.
• Розуміти, як інші SIG Kubernetes та репозиторії впливають на робочий процес SIG Docs, включаючи: команди в k/org, процеси в k/community, втулки в k/test-infra, та роль SIG Architecture. Крім того, розуміти, як працює процес випуску документації Kubernetes.
• Отримати схвалення від спільноти SIG Docs або безпосередньо, або за допомогою консенсусу.
• Виділяти принаймні 5 годин на тиждень (і часто більше) на цю роль протягом мінімум 6 місяців.

Обовʼязки

Роль співголови полягає в обслуговуванні: співголови підвищують можливості учасників, керують процесами та політикою, організовують та проводять зустрічі, планують роботу сортувальників PR-ів, висвітлюють важливість документації в спільноті Kubernetes, забезпечують успішне завершення випусків документації та фокусують SIG Docs на ефективних пріоритетах.

Обовʼязки включають:

• Фокусування SIG Docs на максимальному задоволенні розробників через відмінну документацію
• Втілення кодексу поведінки спільноти та відповідальність за його дотримання серед членів SIG
• Вивчення та встановлення найкращих практик для SIG шляхом оновлення рекомендацій щодо внесення змін
• Організація та проведення зустрічей SIG: щотижневі оновлення статусу, щоквартальні ретроспективи/планування та інші за потребою
• Організація та проведення спринтів документації на заходах KubeCon та інших конференціях
• Рекрутинг та захист інтересів SIG Docs у CNCF та її платинових партнерів, включаючи Google, Oracle, Azure, IBM та Huawei
• Забезпечення безперебійної роботи SIG

Ефективне проведення зустрічей

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

Дотримуйтесь кодексу поведінки спільноти:

• Проводьте шанобливі, інклюзивні дискусії, використовуючи шанобливу, інклюзивну мову.

Встановіть чіткий порядок денний:

• Встановіть чіткий порядок денний тем
• Опублікуйте порядок денний заздалегідь

Для щотижневих зустрічей скопіюйте нотатки з попереднього тижня у розділ "Минулі зустрічі" нотаток

Співпрацюйте для точних нотаток:

• Записуйте обговорення зустрічі
• Розгляньте можливість делегування ролі стенографіста

Чітко та точно призначайте дії:

• Записуйте завдання, відповідального за нього та очікувану дату виконання

Модеруйте за потребою:

• Якщо обговорення відходить від порядку денного, поверніть учасників до поточної теми
• Забезпечте різні стилі обговорення, зберігаючи фокус та поважаючи час учасників

Повага до часу учасників:

Починайте і закінчуйте зустрічі вчасно.

Ефективне використання Zoom:

• Ознайомтесь з керівництвом Zoom для Kubernetes
• Займіть роль ведучого під час входу, ввівши ключ

Запис зустрічей в Zoom

Коли ви готові розпочати запис, натисніть "Record to Cloud".

Коли ви готові зупинити запис, натисніть "Stop".

Відео автоматично завантажується на YouTube.

Завершення роботи співголови SIG (Emeritus)

Дивіться: k/community/sig-docs/offboarding.md

10 - Перегляд аналітики сайту

Ця сторінка містить інформацію про інформаційну аналітичну панель kubernetes.io.

Переглянути панель.

Ця панель побудована за допомогою Google Looker Studio та відображає інформацію, зібрану на kubernetes.io за допомогою Google Analytics 4 з серпня 2022 року.

Використання панелі

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

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

11 - Рекомендації з перекладу українською мовою

Дорогі друзі! Раді вітати вас у спільноті українських учасників проєкту Kubernetes. Ця сторінка створена з метою полегшити вашу роботу в роботі з перекладу документації. Вона містить правила, якими ми керувалися під час перекладу. Будемо дуже вдячні, якщо ви допоможете розширити правила перекладу.

Сподіваємось, ці рекомендації стануть вам у пригоді.

Загальний процес

1. Клонуйте (зробіть форк) репозиторію kubernetes/website.
2. Ознайомтесь з цим документом.
3. Зробіть переклад
4. Створіть пул-реквест в kubernetes/website.

Якщо вам знадобиться допомога, зареєструйтеся в Slack Kubernetes, приєднайтеся до каналу#kubernetes-docs-uk та спитайте там.

Отримання допомоги

Якщо ви виявили вади в перекладеному вмісті, створіть тікет на kubernetes/website додавши в тіло тікета команду Prow — /language uk.

Наявні проблеми/оновлення локалізації

Якщо ви виявили проблеми з перекладеним вмістом і не можете їх негайно виправити, створіть тікет у kubernetes/website з описом що не так, на якій сторінці (посилання) і додайте в опис тікета, з нового рядка, команду Prow — /language uk.

Переклад

• У випадку, якщо у перекладі термін набуває неоднозначності та розуміння тексту ускладнюється, надайте у дужках англійський варіант, наприклад: точки доступу (endpoints). Якщо при перекладі термін втрачає своє значення, краще не перекладати його.
• Назви обʼєктів Kubernetes залишаємо без перекладу і пишемо з великої літери: Service, Pod, Deployment, Volume, Namespace, за винятком терміна node (вузол). Назви обʼєктів Kubernetes вважаємо за іменники ч.р. і відмінюємо за допомогою апострофа: Podʼів, Deploymentʼами.
• Для слів, що закінчуються на приголосний, у родовому відмінку однини використовуємо закінчення -а: Podʼа, Deploymentʼа. Слова, що закінчуються на голосний, не відмінюємо: доступ до Service, за допомогою Namespace. У множині використовуємо англійську форму: користуватися Services, спільні Volumes.
• Частовживані та усталені за межами Kubernetes слова перекладаємо українською і пишемо з малої літери (label → мітка). У випадку, якщо термін для означення обʼєкта Kubernetes вживається у своєму загальному значенні поза контекстом Kubernetes (service як службова програма, deployment як розгортання), перекладаємо його і пишемо з малої літери, наприклад: service discovery → виявлення сервісу, continuous deployment → безперервне розгортання.
• Складені слова вважаємо за власні назви та не перекладаємо (LabelSelector, kube-apiserver).
• Для перевірки закінчень слів у родовому відмінку однини (-а/-я, -у/-ю) використовуйте онлайн словник. Якщо слова немає у словнику, визначте його відмінювання і далі відмінюйте за правилами. Докладніше дивіться тут.
• Для символу тире ― використовуйте символ mdash «—» (—, U+2014) замість двох звичайних тире «–» (–, U+2013), чи дефісу «-» (U+002D)
• Апостроф: використовуйте літеру-апостроф ʼ (U+02BC) замість звичайного апострофа ' (U+0027), чи правої одинарної лапки ’ (U+2019).

Примітки

На поточний момент в перекладі документації активну участь бере @Andygol. Перекладені матеріали можна переглянути в репозиторії на GitHub Andygol/k8s-website в гілці main-uk-wip.

В репозиторії kubernetes/website ви можете знайти Обговорення Translation tooling for Kubernetes localization #45209 щодо використання систем перекладу та інструментів для локалізації документації Kubernetes.

Також ви можете стежити за процесом тестування таких інструментів в тікеті Test translation tooling for localizations #45756