Внесок у код Kubernetes

Ця сторінка показує, як зробити внесок у проєкт kubernetes/kubernetes. Ви можете виправити помилки, знайдені в документації API Kubernetes або вмісті компонентів Kubernetes, таких як kubeadm, kube-apiserver та kube-controller-manager.

Якщо ви хочете відновити довідкову документацію для API Kubernetes або компонентів kube-* з коду upstream, перегляньте наступні інструкції:

Перш ніж ви розпочнете

  • Вам потрібно встановити наступні інструменти:

  • Ваша змінна середовища GOPATH повинна бути встановлена, а розташування etcd повинно бути у вашій змінній середовища PATH.

  • Вам потрібно знати, як створити pull request у репозиторій GitHub. Зазвичай це включає створення форку репозиторію. Для отримання додаткової інформації дивіться Створення Pull Request та Стандартний Workflow Fork & Pull Request на GitHub.

Загальна картина

Довідкова документація для API Kubernetes та компонентів kube-*, таких як kube-apiserver, kube-controller-manager, автоматично генерується з вихідного коду в upstream Kubernetes.

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

Клонування репозиторію Kubernetes

Якщо ви ще не маєте репозиторію kubernetes/kubernetes, отримайте його зараз:

mkdir $GOPATH/src
cd $GOPATH/src
go get github.com/kubernetes/kubernetes

Визначте базову теку вашого клону репозиторію kubernetes/kubernetes. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — $GOPATH/src/github.com/kubernetes/kubernetes. Наступні кроки посилаються на вашу базову теку як <k8s-base>.

Визначте базову теку вашого клону репозиторію kubernetes-sigs/reference-docs. Наприклад, якщо ви слідували попередньому кроку для отримання репозиторію, ваша базова тека — $GOPATH/src/github.com/kubernetes-sigs/reference-docs. Наступні кроки посилаються на ваш базовий каталог як <rdocs-base>.

Редагування вихідного коду Kubernetes

Довідкова документація API Kubernetes автоматично генерується з OpenAPI специфікації, яка створюється з вихідного коду Kubernetes. Якщо ви хочете змінити довідкову документацію API, перший крок — змінити один або кілька коментарів у вихідному коді Kubernetes.

Документація для компонентів kube-* також генерується з вихідного коду upstream. Ви повинні змінити код, повʼязаний з компонентом, який ви хочете виправити, щоб виправити згенеровану документацію.

Зробіть зміни у вихідному коді upstream

Ось приклад редагування коментаря у вихідному коді Kubernetes.

У вашому локальному репозиторії kubernetes/kubernetes, перейдіть на основну гілку і переконайтеся, що вона оновлена:

cd <k8s-base>
git checkout master
git pull https://github.com/kubernetes/kubernetes master

Припустимо, що у цьому вихідному файлі в основній гілці є помилка "atmost":

kubernetes/kubernetes/staging/src/k8s.io/api/apps/v1/types.go

У вашому локальному середовищі відкрийте types.go і змініть "atmost" на "at most".

Перевірте, що ви змінили файл:

git status

Вивід показує, що ви в основній гілці та що вихідний файл types.go був змінений:

On branch master
...
    modified:   staging/src/k8s.io/api/apps/v1/types.go

Збережіть відредагований файл

Виконайте git add і git commit, щоб зберегти зміни, які ви внесли до цього моменту. У наступному кроці ви зробите другий коміт. Важливо зберігати ваші зміни в окремих комітах.

Перейдіть до <k8s-base> і запустіть ці скрипти:

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Виконайте git status, щоб побачити, що було згенеровано.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/openapi-spec/v3/apis__apps__v1_openapi.json
    modified:   pkg/generated/openapi/zz_generated.openapi.go
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types_swagger_doc_generated.go

Перегляньте вміст api/openapi-spec/swagger.json, щоб переконатися, що помилка виправлена. Наприклад, ви можете виконати git diff -a api/openapi-spec/swagger.json. Це важливо, оскільки swagger.json є вхідними даними для другого етапу процесу генерації документації.

Виконайте git add і git commit, щоб зберегти ваші зміни. Тепер у вас є два коміти: один з відредагованим файлом types.go, і один, що містить згенеровану OpenAPI специфікацію та супутні файли. Залишить ці два коміти окремо. Тобто, не зливайте ваші коміти.

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

PR 57758 є прикладом pull request, який виправляє помилку в коді Kubernetes.

Cherry-pick вашого коміту у релізну гілку

У попередньому розділі ви відредагували файл в основній гілці та потім запустили скрипти для генерації OpenAPI специфікації та супутніх файлів. Потім ви подали свої зміни у pull request до основної гілки репозиторію kubernetes/kubernetes. Тепер припустимо, що ви хочете повернути вашу зміну в релізну гілку. Наприклад, якщо основна гілка використовується для розробки версії Kubernetes 1.32, і ви хочете повернути вашу зміну у гілку release-1.31.

Згадайте, що ваш pull request має два коміти: один для редагування types.go і один для файлів, згенерованих скриптами. Наступний крок — запропонувати cherry pick вашого першого коміту у гілку release-1.31. Ідея полягає в тому, щоб зробити cherry-pick коміту, що редагував types.go, але не коміту, що має результати запуску скриптів. Для інструкцій дивіться Запропонувати Cherry Pick.

Коли у вас є pull request для cherry-pick вашого коміту у гілку release-1.31, наступний крок — запустити ці скрипти в гілці release-1.31 у вашому локальному середовищі.

./hack/update-codegen.sh
./hack/update-openapi-spec.sh

Тепер додайте коміт до вашого cherry-pick pull request, що містить нещодавно згенеровану OpenAPI специфікацію та супутні файли. Слідкуйте за вашим pull request, поки він не буде злитий у гілку release-1.31.

На цьому етапі й основна гілка, й гілка release-1.31 містять ваш оновлений файл types.go та набір згенерованих файлів, що відображають зміну, яку ви внесли в types.go. Зазначте, що згенерована OpenAPI специфікація та інші згенеровані файли в гілці release-1.31 не обовʼязково будуть такими ж, як згенеровані файли в основній гілці. Згенеровані файли в гілці release-1.31 містять API елементи лише з Kubernetes 1.31. Згенеровані файли в основній гілці можуть містити API елементи, які не є в 1.31, але розробляються для 1.32.

Генерація опублікованих довідкових документів

Попередній розділ показав, як редагувати вихідний файл і потім згенерувати декілька файлів, включаючи api/openapi-spec/swagger.json у репозиторії kubernetes/kubernetes. Файл swagger.json є файлом визначення OpenAPI, який використовується для генерації документації API.

Тепер ви готові слідувати посібнику Генерація довідкової документації для API Kubernetes, щоб згенерувати опубліковану довідкову документацію API Kubernetes.

Що далі

Змінено August 22, 2024 at 6:59 PM PST: upstream sync (b7f2b32b60)