Кожен великий випуск 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. Кожен випуск має підтеку в теці /sig-release/tree/master/releases/. Підтека містить розклад випуску, чернетку приміток до випуску та документ зі списком усіх членів команди випуску.
Розклад випуску містить посилання на всі інші документи, зустрічі, протоколи зустрічей і віхи, повʼязані з випуском. Він також містить інформацію про цілі та графік випуску й будь-які особливі процеси для цього випуску. Ближче до кінця документа наведено визначення кількох термінів, повʼязаних із випуском.
Цей документ також містить посилання на Feature tracking sheet — офіційний спосіб дізнатися про всі нові можливості, заплановані до випуску.
Документ команди випуску вказує, хто відповідає за кожну роль у випуску. Якщо незрозуміло, до кого звернутися щодо конкретної можливості чи вашого запитання, або відвідайте зустріч випуску й поставте запитання там, або зверніться до керівника випуску, щоб він вас спрямував.
Чернетка приміток до випуску — гарне місце, щоб дізнатися про конкретні можливості, зміни, застарівання та інше щодо випуску. Вміст не остаточний до пізнього етапу циклу випуску, тож користуйтеся ним обережно.
Таблиця відстеження можливостей для конкретного випуску Kubernetes містить перелік усіх можливостей, запланованих для випуску. Кожен рядок містить назву можливості, посилання на її основний тікет на GitHub, рівень стабільності (Alpha, Beta або Stable), SIG та особу, відповідальних за реалізацію, чи потрібна документація, чернетку примітки до випуску для можливості та чи її злито. Майте на увазі таке:
Цей розділ містить інформацію для членів інших SIG Kubernetes, які документують нові можливості для випуску.
Якщо ви член SIG, яка розробляє нову можливість для Kubernetes, вам потрібно працювати з SIG Docs, щоб вашу можливість задокументували вчасно до випуску. Перегляньте таблицю відстеження можливостей або уточніть у Slack-каналі Kubernetes #sig-release подробиці розкладу та терміни.
dev-1.38 у репозиторії kubernetes/website з невеликим комітом, який згодом зміните. Щоб створити чернетку pull request, у спадному меню Create Pull Request виберіть Create Draft Pull Request, а потім натисніть Draft Pull Request.Якщо ваша можливість не потребує змін документації, переконайтеся, що команда sig-release про це знає, — повідомте в Slack-каналі #sig-release. Якщо можливість потребує документації, але PR не створено, можливість можуть вилучити з milestone.
Коли будете готові, наповніть свій placeholder PR документацією можливості та змініть стан PR з чернетки на ready for review. Щоб позначити pull request як готовий до рецензування, перейдіть до блоку злиття й натисніть Ready for review.
Якнайкраще опишіть свою можливість і те, як її використовувати. Якщо вам потрібна допомога зі структурою документації, запитайте в Slack-каналі #sig-docs.
Коли ви завершите вміст, його рецензує особа з документації, призначена для вашої можливості. Для забезпечення технічної точності вміст також може потребувати технічного рецензування від відповідних SIG. Використайте їхні пропозиції, щоб довести вміст до готовності до випуску.
Якщо ваша можливість потребує документації, а першої чернетки вмісту не отримано, можливість можуть вилучити з milestone.
Якщо ваша можливість на етапі Alpha або Beta і прихована за функціональною можливістю (feature gate), для неї потрібен файл функціональної можливості в content/en/docs/reference/command-line-tools-reference/feature-gates/. Назвою файлу має бути назва функціональної можливості з суфіксом .md. Як має виглядати ваш файл, можна подивитися в інших файлах цієї теки. Зазвичай достатньо одного абзацу; для довших пояснень додайте документацію деінде й посилайтеся на неї.
Також, щоб ваша функціональна можливість зʼявилася в таблиці Функціональні можливості Alpha/Beta, додайте такі відомості у front matter свого файлу опису Markdown:
stages:
- stage: <alpha/beta/stable/deprecated> # Вкажіть етап розробки функціональної можливості
defaultValue: <true or false> # Встановіть true, якщо стандартно ввімкнено, інакше false
fromVersion: <Version> # Версія, з якої доступна функціональна можливість
toVersion: <Version> # (Необовʼязково) Версія, до якої функціональна можливість доступна
Для зовсім нових функціональних можливостей також потрібен окремий опис; створіть новий файл Markdown у content/en/docs/reference/command-line-tools-reference/feature-gates/ (використовуйте інші файли як шаблон).
Коли ви змінюєте функціональну можливість зі стандартно вимкненої на стандартно ввімкнену, може знадобитися змінити й іншу документацію (не лише список функціональних можливостей). Звертайте увагу на формулювання на кшталт «Поле exampleSetting є beta-полем і стандартно вимкнене. Його можна ввімкнути, увімкнувши функціональну можливість ProcessExampleThings.»
Якщо ваша можливість стала GA або застарілою (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 ще не злито в гілку dev-1.38 до крайнього терміну випуску, працюйте з відповідальною за документацію особою, яка керує випуском, щоб встигнути до терміну. Якщо ваша можливість потребує документації, а документація не готова, можливість можуть вилучити з milestone.