Внесення нового вмісту

• 1: Попередній локальний перегляд змін
• 2: Документування можливості для випуску
• 3: Подання прикладів використання

flowchart LR
    subgraph second[Перш ніж розпочати]
    direction TB
    S[ ] -.-
    A[Підпишіть CNCF CLA] --> B[Оберіть гілку Git]
    B --> C[Одна мова на PR]
    C --> F[Ознайомтесь з
інструментами для участі]
    end
    subgraph first[Основи участі]
    direction TB
       T[ ] -.-
       D[Пишіть документи в markdown
та збирайте сайт за допомогою Hugo] --- E[сирці на GitHub]
       E --- G[Тека '/content/../docs' містить документи
для кількох мов]
       G --- H[Ознайомтесь з типом вмісту сторінок Hugo
та shortcodes]
    end

    first ----> second

classDef grey fill:#dddddd,stroke:#ffffff,stroke-width:px,color:#000000, font-size:15px;
classDef white fill:#ffffff,stroke:#000,stroke-width:px,color:#000,font-weight:bold
classDef spacewhite fill:#ffffff,stroke:#fff,stroke-width:0px,color:#000
class A,B,C,D,E,F,G,H grey
class S,T spacewhite
class first,second white

1 - Попередній локальний перегляд змін

Before you're going to open a new PR, previewing your changes is recommended. A preview lets you catch build errors or markdown formatting problems.

Попередній перегляд змін локально

Ви можете або зібрати образ контейнера вебсайту, або запустити Hugo локально. Збирання образу контейнера повільніше, але показує shortcodes Hugo, що може бути корисним для налагодження.

• Hugo в контейнері
• Hugo в командному рядку

Усунення несправностей

error: failed to transform resource: TOCSS: failed to transform "scss/main.scss" (text/x-scss): this feature is not available in your current Hugo version

З технічних причин Hugo постачається у двох наборах бінарних файлів. Поточний вебсайт працює лише на версії Hugo Extended. На сторінці випусків шукайте архіви з extended у назві. Щоб переконатися, виконайте hugo version і знайдіть слово extended.

Усунення несправностей macOS через забагато відкритих файлів

Якщо ви запускаєте make serve в macOS і отримуєте таку помилку:

ERROR 2020/08/01 19:09:18 Error: listen tcp 127.0.0.1:1313: socket: too many open files
make: *** [serve] Error 1

Спробуйте перевірити поточне обмеження на кількість відкритих файлів:

launchctl limit maxfiles

Потім виконайте такі команди (адаптовано з https://gist.github.com/tombigel/d503800a282fcadbee14b537735d202c):

#!/bin/sh

# These are the original gist links, linking to my gists now.
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxfiles.plist
# curl -O https://gist.githubusercontent.com/a2ikm/761c2ab02b7b3935679e55af5d81786a/raw/ab644cb92f216c019a2f032bbf25e258b01d87f9/limit.maxproc.plist

curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxfiles.plist
curl -O https://gist.githubusercontent.com/tombigel/d503800a282fcadbee14b537735d202c/raw/ed73cacf82906fdde59976a0c8248cce8b44f906/limit.maxproc.plist

sudo mv limit.maxfiles.plist /Library/LaunchDaemons
sudo mv limit.maxproc.plist /Library/LaunchDaemons

sudo chown root:wheel /Library/LaunchDaemons/limit.maxfiles.plist
sudo chown root:wheel /Library/LaunchDaemons/limit.maxproc.plist

sudo launchctl load -w /Library/LaunchDaemons/limit.maxfiles.plist

Це працює як для macOS Catalina, так і для Mojave.

Unable to find image 'gcr.io/k8s-staging-sig-docs/k8s-website-hugo:VERSION' locally

Якщо ви запускаєте make container-serve і бачите цю помилку, причиною можуть бути локальні зміни у файлах, визначених у $IMAGE_VERSION файлу Makefile.

Версія образу вебсайту містить хеш, який генерується на основі вмісту перелічених файлів. Наприклад, якщо 1b9242684415 — хеш цих файлів, образ вебсайту називатиметься k8s-website-hugo:v0.133.0-1b9242684415. Виконання make container-serve спробує завантажити такий образ із GCR вебсайту Kubernetes. Якщо це не поточна версія, ви побачите помилку про те, що такого образу немає.

Якщо вам потрібно внести зміни в ці файли й переглянути вебсайт, доведеться зібрати локальний образ замість завантаження готового. Для цього виконайте make container-image.

Інші проблеми

Якщо у вас виникли інші проблеми з локальним запуском вебсайту та/або попереднім переглядом змін, не соромтеся створити тікет у репозиторії GitHub kubernetes/website.

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. Кожен випуск має підтеку в теці /sig-release/tree/master/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 подробиці розкладу та терміни.

Відкрийте placeholder PR

1. Відкрийте чернетку pull request до гілки dev-1.38 у репозиторії 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 готовий до рецензування

Коли будете готові, наповніть свій placeholder PR документацією можливості та змініть стан PR з чернетки на ready for review. Щоб позначити pull request як готовий до рецензування, перейдіть до блоку злиття й натисніть Ready for review.

Якнайкраще опишіть свою можливість і те, як її використовувати. Якщо вам потрібна допомога зі структурою документації, запитайте в Slack-каналі #sig-docs.

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

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

Функціональні можливості (feature gates)

Якщо ваша можливість на етапі 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 відрецензовано й готово до злиття

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

3 - Подання прикладів використання

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

Приклади використання ретельно рецензують, перш ніж затвердити.

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

Перегляньте вихідний код наявних прикладів використання.

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