Edit This Page

Участие в основном коде 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
hack/update-api-reference-docs.sh

Выполните команду git status, чтобы посмотреть, какие файлы изменились.

On branch master
...
    modified:   api/openapi-spec/swagger.json
    modified:   api/swagger-spec/apps_v1.json
    modified:   docs/api-reference/apps/v1/definitions.html
    modified:   staging/src/k8s.io/api/apps/v1/generated.proto
    modified:   staging/src/k8s.io/api/apps/v1/types.go
    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.

Заметка: Не всегда легко правильно определить, какой исходный файл нужно изменить. В предыдущем примере нужный исходный файл находится в директории staging в репозитории kubernetes/kubernetes. Однако в вашей ситуации файл для изменения может находится в другом месте, нежели чем в директории staging. Для получения помощи изучите файлы README в репозитории kubernetes/kubernetes и в смежных репозиториях, например, kubernetes/apiserver.

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

В предыдущем разделе вы отредактировали файл в ветке 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.

Что дальше