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

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

1 - Створення pull request

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

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

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

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

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

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

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

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

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

   Примітка:

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

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

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

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

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

   Примітка:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

1. У вікні термінала, клонуйте ваш форк та оновіть тему [Docsy Hugo(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.

Що далі

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

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/Feature таблиці до таблиці Функціональних можливостей для стабільних або застарілих функцій. Наприклад:

stages:
  - stage: alpha
    defaultValue: false
    fromVersion: "1.12"
    toVersion: "1.12"
  - stage: beta
    defaultValue: true
    fromVersion: "1.13"
    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 - Дописи в блог та приклади використань

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

Блог 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 співпрацюватимуть з вами над усіма прикладами використання.

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

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