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

Кожен великий випуск 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).

Змінено October 21, 2024 at 1:36 PM PST: upstream sync (c606a3ee0c)