Публікація статей у блогах Kubernetes

Існує два офіційні блоги Kubernetes, і CNCF має свій власний блог, де ви також можете розповідати про Kubernetes. У головному блозі Kubernetes ми (проєкт Kubernetes) хочемо публікувати статті з різними поглядами та напрямками, які повʼязані з Kubernetes.

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

Написання статей для блогу(ів) Kubernetes

Як автор, ви маєте три різні шляхи до публікації.

Створення pull request

Другий шлях до написання текстів для наших блогів - це почати безпосередньо з pull request на GitHub. Команда блогу насправді не рекомендує цього робити; GitHub досить корисний для спільної роботи над кодом, але не ідеально підходить для роботи з текстами.

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

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

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

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

Планування розміщення статей

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

У розділі про написання статті в блозі пояснюється, що для цього потрібно зробити:

спочатку не вказуйте дату для статті
однак, позначте статтю як чернетку (поставте draft: true на титульному аркуші).

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

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

Написання статті

Після того, як ви пройдете процедуру відбору, ми заохочуємо вас скористатися HackMD (редактором Markdown) або Google Doc, щоб поділитися версією тексту статті, яку можна буде редагувати. Ваш колега по написанню статті може прочитати чернетку тексту, а потім або безпосередньо внести свої пропозиції, або надати інший відгук. Він також повинен повідомити вас, якщо ваш відгук не відповідає [керівним принципам написання статей] (/docs/contribute/blog/guidelines/).

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

Початкові адміністративні кроки

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

Початкова редакція

Команда блогу рекомендує вам використовувати HackMD (редактор Markdown) або Google doc, щоб підготувати і поділитися початковою редакцією тексту статті, яку можна редагувати в реальному часі.

Примітка:

Якщо ви вирішите скористатися Документами Google, ви можете перевести ваш документ у режим розмітки.

Ваш товариш по написанню статті може надавати коментарі та/або відгуки до вашої чернетки і перевірятиме (або повинен перевіряти), чи відповідає вона настановам. Водночас, ви станете його товаришем по написанню і можете слідувати інструкції, яка пояснює, як ви будете підтримувати їхню роботу.

На цьому етапі не хвилюйтеся надто сильно про правильність форматування Markdown.

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

Markdown для публікації

Ознайомтеся з форматом розмітки для наявних дописів у блозі в репозиторії вебсайту на GitHub.

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

У репозиторії GitHub натисніть кнопку Створити новий файл. Скопіюйте наявний контент з HackMD або Google Docs, а потім вставте його в редактор. Нижче в цьому розділі ми розповімо докладніше про те, що буде в цьому файлі. Назвіть файл так, щоб він відповідав запропонованому заголовку публікації в блозі, але не ставте дату в назві файлу. Рецензенти блогу будуть працювати з вами, щоб встановити остаточну назву файлу і дату, коли стаття буде опублікована.

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

Front matter

Файл Markdown, який ви створюєте, повинен використовувати YAML-формат Hugo front matter.

Ось приклад:

---
layout: blog
title: "Your Title Here"
draft: true # буде змінено на "date: YYYY-MM-DD" перед публікацією
slug: lowercase-text-for-link-goes-here-no-spaces # опціонально
author: >
  Author-1 (Affiliation),
  Author-2 (Affiliation),
  Author-3 (Affiliation)  
---

спочатку не вказуйте дату для статті
однак, визначте статтю як чернетку (поставте draft: true у front matter статті).

Зміст статті

Переконайтеся, що ви використовуєте заголовки Markdown другого рівня (##, а не #) як найвищий рівень заголовків у статті. Заголовок title, який ви встановили на титульному аркуші, стає заголовком першого рівня для цієї сторінки.

Ви повинні слідувати посібнику зі стилів, але з наступними винятками:

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

Схеми та ілюстрації

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

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

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

нема потреби підписувати діаграми як Зображення 1, Зображення 2 і т.д.

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

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

Повідомлення коміту

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

Приклади хороших повідомлень про фіксацію змін:

Add blog post on the foo kubernetes feature
blog: foobar announcement

Приклади поганих повідомлень про фіксацію змін:

Placeholder commit for announcement about foo
Add blog post
asdf
initial commit
draft post

Стискання комітів

Після того, як ви вирішите, що стаття готова до злиття, вам слід зробити squash комітів у вашому pull request; якщо ви не знаєте, як це зробити, зверніться за допомогою до команди блогу.

Змінено April 18, 2025 at 5:12 PM PST: sync upstream (ebdf664e4b)