Information in this document may be out of date

This document has an older update date than the original, so the information it contains may be out of date. If you're able to read English, see the English version for the most up-to-date information: Contributing to the Upstream Kubernetes Code

Участие в основном коде Kubernetes

На этой странице показано, как поучаствовать в основном содержимом проекта kubernetes/kubernetes. Вы можете исправить баги, найденные в документации по API Kubernetes или содержимом таких компонентов Kubernetes, как kubeadm, kube-apiserver и kube-controller-manager.

Если вместо этого вы хотите перегенерировать справочную документацию для API Kubernetes или компонентов с именем kube-* в основном коде, изучите следующие инструкции:

Подготовка к работе

Рассмотрение процесса в целом

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

Если вы заметили баги в сгенерированной документации, попробуйте его исправить через пулреквест в основной проект.

Клонирование репозитория 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-* также генерируется из основного исходного кода. Для изменения генерируемой документации вам нужно изменить соответствующий код компонента.

Внесение изменений в основной исходный код

Рассмотрим пример редактирования комментария в исходном коде Kubernetes.

В вашем локальном репозитории kubernetes/kubernetes переключитесь на ветку master и проверьте, что она актуальна:

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

Предположим, что в исходном файле в ветке master есть опечатка "atmost":

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

В вашем локальном окружении откройте types.go и измените "atmost" на "at most".

Убедитесь, что вы изменили файл:

git status

Вывод этой команды покажет, что вы находитесь в ветке master и был изменён исходный файл types.go:

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

Фиксация отредактированного файла

Выполните команду git add и git commit, чтобы зафиксировать внесенные вами изменения. На следующем шаге вы сделаете второй коммит. Следует отметить, что ваши изменения должны быть разделены на коммита.

Генерация спецификации OpenAPI и сопутствующих файлов

Перейдите в директорию <k8s-base> и выполните следующие скрипты:

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.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 и сопутствующие файлы. Оформляйте эти изменения в виде двух отдельных коммитов. Это означает, что не нужно объединять коммиты.

Отправьте свои изменения как пулреквест в ветку master репозитория kubernetes/kubernetes. Отслеживайте пулреквест и по мере необходимости отвечайте на комментарии рецензента. Не забывайте отслеживать активность в пулреквест до тех пор, пока он не будет принят.

PR 57758 — пример пулреквеста, который исправляет опечатку в исходном коде Kubernetes.

Применение вашего коммита в ветку выпуска

В предыдущем разделе вы отредактировали файл в ветке master, а затем запустили скрипты для генерации спецификации OpenAPI и смежных файлов. Затем вы отправили свои изменения в виде пулреквеста в ветку master репозитория kubernetes/kubernetes. Теперь представим, что вам нужно бэкпортировать изменения в ветку выпуска. К примеру, ветка master используется для разработки Kubernetes версии 1.10, а вы хотите применить ваши изменения в ветке release-1.9.

Напомним, что в вашем пулреквесте есть два коммита: первый для редактирования types.go, а второй — для файлов, сгенерированных скриптами. Следующий шаг — применить сделанный вами первый коммит в ветку release-1.9. Суть в том, чтобы выбрать коммит, который изменяет файл types.go, а не коммит с результатами выполнения скриптов. За инструкциями обратитесь к странице Propose a Cherry Pick.

Когда в вашем пулреквесте есть определённый коммит, который нужно применить в ветке release-1.9, вам нужно запустить перечисленные ниже скрипты в этой вете из вашего локального окружения.

hack/update-generated-swagger-docs.sh
hack/update-openapi-spec.sh
hack/update-generated-protobuf.sh
hack/update-api-reference-docs.sh

Теперь зафиксируйте изменения в вашем пулреквесте с применённым коммитом, теперь там будет сгенерированная спецификация OpenAPI и связанные с ней файлы. Отслеживайте этот пулреквест до тех пор, пока он не будет объединен в ветке release-1.9.

Сейчас у вас и в ветке master, и в ветке release-1.9 есть обновленный файл types.go вместе с множеством сгенерированных файлов, в которых отражаются изменения, внесенные вами в types.go. Обратите внимание, что сгенерированная спецификация OpenAPI и другие сгенерированные файлы в ветке release-1.9 не обязательно совпадают с сгенерированными файлами в ветке master. Сгенерированные файлы в ветке release-1.9 содержат элементы API только из Kubernetes 1.9. Сгенерированные файлы в ветке master могут содержать элементы API не только для версии 1.9, но и для 1.10, которая ещё находится в разработке.

Генерация справочной документации

В предыдущем разделе было показано, как отредактировать исходный файл, а затем сгенерировать несколько файлов, включая api/openapi-spec/swagger.json в репозитории kubernetes/kubernetes. Файл swagger.json — это файл определения OpenAPI, который используется для генерации справочной документации API.

Теперь вы можете приступить к изучению руководству Генерация справочной документации для API Kubernetes, чтобы создать справочную документацию API Kubernetes.

Что дальше

Изменено May 05, 2022 at 12:58 AM PST: [ru] revise page “Contributing to the Upstream Kubernetes Code” (0d26285c2b)