Kubernetes公式ドキュメント日本語版のバージョン管理を考えてみた

はじめに

先日、Kubernetes公式ドキュメント日本語版（以下、kubernetes-docs-ja）の翻訳済みページは原文のv1.18に追従完了しました。これらは画面右上の「バージョン」を選択しない、または、最新版を選択することで参照できます。「バージョン」からv1.18を選択すると、release-1.18ブランチが作成された時点のスナップショット、つまり追従前のやや古めのコンテンツが表示されます。

現在、原文のv1.19に追従するべく多くのIssueが作られはじめました。v1.19対応が完了してmasterブランチにマージされるとv1.18のドキュメントは参照する術がありません。私は、kubernetes-docs-jaでも選択したバージョンのドキュメントを表示するようにしたいと強く思い、v1.17頃から頭を捻っていました。ついに、美しくはないものの解決案が浮かんだので、kubernetes-docs-ja-maintainersに提案してみます。

TL;DR

すべてのファイルを削除し、ごっそり置き換えます。

git rm -r content/ja/docs
cp -r path/to/master/content/ja/docs content/ja/docs

解決案

devブランチ（例: dev-1.18-ja.2）をmasterとリリースブランチの両方にマージするのが最適と考えていましたが、git rebaseするのが大変そうです。どちらかにマージした後にgit cherry-pickする方法も模索しましたが、しっくりきませんでした。

gitを使ってうまいことするのはあきらめました。

作業用ディレクトリとしてリリースブランチをcloneします。

git clone --single-branch --branch release-1.18 https://github.com/kubernetes/website.git release-1.18
cd release-1.18
git switch -c release-1.18-ja

release-1.18ディレクトリと同じ階層にmasterブランチをもとにしたmasterディレクトリが存在することとします。

すべてのファイルを削除し、ごっそり置き換えます。

git rm -r content/ja/docs
cp -r ../master/content/ja/docs content/ja/docs
git add content/ja/docs

git statusの出力は次のようになります。

On branch release-1.18-ja
Changes to be committed:
  (use "git restore --staged <file>..." to unstage)
	modified:   content/ja/docs/_index.md
	modified:   content/ja/docs/concepts/architecture/cloud-controller.md
	modified:   content/ja/docs/concepts/architecture/controller.md
	modified:   content/ja/docs/concepts/architecture/nodes.md
	modified:   content/ja/docs/concepts/cluster-administration/certificates.md
	new file:   content/ja/docs/concepts/cluster-administration/cloud-providers.md
	new file:   content/ja/docs/concepts/cluster-administration/manage-deployment.md
	modified:   content/ja/docs/concepts/cluster-administration/networking.md
	new file:   content/ja/docs/concepts/cluster-administration/proxies.md
	modified:   content/ja/docs/concepts/configuration/manage-resources-containers.md
	modified:   content/ja/docs/concepts/configuration/overview.md
	modified:   content/ja/docs/concepts/configuration/secret.md
	modified:   content/ja/docs/concepts/containers/_index.md
	modified:   content/ja/docs/concepts/containers/container-lifecycle-hooks.md
	new file:   content/ja/docs/concepts/containers/images.md
	modified:   content/ja/docs/concepts/containers/runtime-class.md
	modified:   content/ja/docs/concepts/extend-kubernetes/_index.md
	modified:   content/ja/docs/concepts/extend-kubernetes/api-extension/apiserver-aggregation.md
	modified:   content/ja/docs/concepts/extend-kubernetes/api-extension/custom-resources.md
	modified:   content/ja/docs/concepts/extend-kubernetes/extend-cluster.md
	modified:   content/ja/docs/concepts/extend-kubernetes/operator.md
	modified:   content/ja/docs/concepts/overview/components.md
	modified:   content/ja/docs/concepts/overview/kubernetes-api.md
	modified:   content/ja/docs/concepts/overview/what-is-kubernetes.md
	modified:   content/ja/docs/concepts/overview/working-with-objects/common-labels.md
	modified:   content/ja/docs/concepts/overview/working-with-objects/field-selectors.md
	modified:   content/ja/docs/concepts/overview/working-with-objects/kubernetes-objects.md
	modified:   content/ja/docs/concepts/overview/working-with-objects/labels.md
	modified:   content/ja/docs/concepts/overview/working-with-objects/namespaces.md
	modified:   content/ja/docs/concepts/policy/resource-quotas.md
	renamed:    content/ja/docs/concepts/configuration/assign-pod-node.md -> content/ja/docs/concepts/scheduling-eviction/assign-pod-node.md
	modified:   content/ja/docs/concepts/scheduling-eviction/kube-scheduler.md
	modified:   content/ja/docs/concepts/scheduling-eviction/taint-and-toleration.md
	new file:   content/ja/docs/concepts/security/overview.md
	new file:   content/ja/docs/concepts/security/pod-security-standards.md
	modified:   content/ja/docs/concepts/services-networking/_index.md
	modified:   content/ja/docs/concepts/services-networking/connect-applications-service.md
	modified:   content/ja/docs/concepts/services-networking/dns-pod-service.md
	new file:   content/ja/docs/concepts/services-networking/endpoint-slices.md
	modified:   content/ja/docs/concepts/services-networking/ingress-controllers.md
	modified:   content/ja/docs/concepts/services-networking/ingress.md
	new file:   content/ja/docs/concepts/services-networking/network-policies.md
	modified:   content/ja/docs/concepts/services-networking/service.md
	modified:   content/ja/docs/concepts/storage/persistent-volumes.md
	new file:   content/ja/docs/concepts/storage/storage-capacity.md
	modified:   content/ja/docs/concepts/storage/volume-pvc-datasource.md
	modified:   content/ja/docs/concepts/workloads/controllers/cron-jobs.md
	modified:   content/ja/docs/concepts/workloads/controllers/daemonset.md
	modified:   content/ja/docs/concepts/workloads/controllers/deployment.md
	modified:   content/ja/docs/concepts/workloads/controllers/garbage-collection.md
	deleted:    content/ja/docs/concepts/workloads/controllers/job.md
	modified:   content/ja/docs/concepts/workloads/controllers/replicaset.md
	modified:   content/ja/docs/concepts/workloads/controllers/statefulset.md
	modified:   content/ja/docs/concepts/workloads/controllers/ttlafterfinished.md
	new file:   content/ja/docs/concepts/workloads/pods/ephemeral-containers.md
	modified:   content/ja/docs/concepts/workloads/pods/init-containers.md
	modified:   content/ja/docs/concepts/workloads/pods/pod-lifecycle.md
	modified:   content/ja/docs/concepts/workloads/pods/pod-overview.md
	deleted:    content/ja/docs/concepts/workloads/pods/pod.md
	modified:   content/ja/docs/concepts/workloads/pods/podpreset.md
	modified:   content/ja/docs/contribute/localization.md
	new file:   content/ja/docs/contribute/review/_index.md
	new file:   content/ja/docs/contribute/review/reviewing-prs.md
	new file:   content/ja/docs/contribute/style/content-guide.md
	new file:   content/ja/docs/contribute/style/content-organization.md
	new file:   content/ja/docs/contribute/suggesting-improvements.md
	modified:   content/ja/docs/home/supported-doc-versions.md
	modified:   content/ja/docs/reference/_index.md
	modified:   content/ja/docs/reference/access-authn-authz/authentication.md
	new file:   content/ja/docs/reference/access-authn-authz/rbac.md
	modified:   content/ja/docs/reference/command-line-tools-reference/feature-gates.md
	new file:   content/ja/docs/reference/command-line-tools-reference/kubelet-authentication-authorization.md
	new file:   content/ja/docs/reference/glossary/cloud-controller-manager.md
	modified:   content/ja/docs/reference/glossary/control-plane.md
	modified:   content/ja/docs/reference/glossary/deployment.md
	modified:   content/ja/docs/reference/glossary/kube-apiserver.md
	modified:   content/ja/docs/reference/glossary/node.md
	modified:   content/ja/docs/reference/glossary/platform-developer.md
	modified:   content/ja/docs/reference/glossary/statefulset.md
	modified:   content/ja/docs/reference/glossary/volume.md
	modified:   content/ja/docs/reference/kubectl/cheatsheet.md
	new file:   content/ja/docs/reference/kubectl/jsonpath.md
	modified:   content/ja/docs/reference/kubectl/overview.md
	new file:   content/ja/docs/reference/tools.md
	modified:   content/ja/docs/setup/_index.md
	modified:   content/ja/docs/setup/best-practices/certificates.md
	modified:   content/ja/docs/setup/best-practices/cluster-large.md
	modified:   content/ja/docs/setup/best-practices/multiple-zones.md
	modified:   content/ja/docs/setup/best-practices/node-conformance.md
	modified:   content/ja/docs/setup/learning-environment/minikube.md
	modified:   content/ja/docs/setup/production-environment/container-runtimes.md
	modified:   content/ja/docs/setup/production-environment/on-premises-vm/cloudstack.md
	modified:   content/ja/docs/setup/production-environment/tools/kops.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/create-cluster-kubeadm.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/ha-topology.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/high-availability.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/kubelet-integration.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/self-hosting.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/setup-ha-etcd-with-kubeadm.md
	modified:   content/ja/docs/setup/production-environment/tools/kubeadm/troubleshooting-kubeadm.md
	modified:   content/ja/docs/setup/production-environment/tools/kubespray.md
	modified:   content/ja/docs/setup/production-environment/turnkey/aws.md
	deleted:    content/ja/docs/setup/production-environment/turnkey/clc.md
	modified:   content/ja/docs/setup/production-environment/turnkey/gce.md
	modified:   content/ja/docs/setup/production-environment/turnkey/icp.md
	modified:   content/ja/docs/setup/production-environment/windows/intro-windows-in-kubernetes.md
	deleted:    content/ja/docs/setup/production-environment/windows/kubecluster.ps1-install.gif
	deleted:    content/ja/docs/setup/production-environment/windows/kubecluster.ps1-join.gif
	deleted:    content/ja/docs/setup/production-environment/windows/kubecluster.ps1-reset.gif
	modified:   content/ja/docs/setup/production-environment/windows/user-guide-windows-containers.md
	deleted:    content/ja/docs/setup/production-environment/windows/user-guide-windows-nodes.md
	modified:   content/ja/docs/setup/release/version-skew-policy.md
	modified:   content/ja/docs/tasks/_index.md
	modified:   content/ja/docs/tasks/access-application-cluster/_index.md
	modified:   content/ja/docs/tasks/access-application-cluster/communicate-containers-same-pod-shared-volume.md
	modified:   content/ja/docs/tasks/access-application-cluster/configure-access-multiple-clusters.md
	modified:   content/ja/docs/tasks/access-application-cluster/connecting-frontend-backend.md
	modified:   content/ja/docs/tasks/access-application-cluster/list-all-running-container-images.md
	modified:   content/ja/docs/tasks/access-application-cluster/service-access-application-cluster.md
	modified:   content/ja/docs/tasks/access-application-cluster/web-ui-dashboard.md
	modified:   content/ja/docs/tasks/administer-cluster/_index.md
	modified:   content/ja/docs/tasks/administer-cluster/coredns.md
	modified:   content/ja/docs/tasks/administer-cluster/developing-cloud-controller-manager.md
	modified:   content/ja/docs/tasks/administer-cluster/enabling-endpointslices.md
	new file:   content/ja/docs/tasks/administer-cluster/kubeadm/adding-windows-nodes.md
	new file:   content/ja/docs/tasks/administer-cluster/kubeadm/upgrading-windows-nodes.md
	new file:   content/ja/docs/tasks/administer-cluster/manage-resources/memory-constraint-namespace.md
	new file:   content/ja/docs/tasks/administer-cluster/nodelocaldns.md
	modified:   content/ja/docs/tasks/administer-cluster/running-cloud-controller.md
	new file:   content/ja/docs/tasks/configmap-secret/_index.md
	new file:   content/ja/docs/tasks/configmap-secret/managing-secret-using-kubectl.md
	modified:   content/ja/docs/tasks/configure-pod-container/_index.md
	modified:   content/ja/docs/tasks/configure-pod-container/assign-cpu-resource.md
	modified:   content/ja/docs/tasks/configure-pod-container/assign-memory-resource.md
	modified:   content/ja/docs/tasks/configure-pod-container/attach-handler-lifecycle-event.md
	modified:   content/ja/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes.md
	modified:   content/ja/docs/tasks/configure-pod-container/configure-pod-configmap.md
	modified:   content/ja/docs/tasks/configure-pod-container/quality-service-pod.md
	modified:   content/ja/docs/tasks/debug-application-cluster/_index.md
	modified:   content/ja/docs/tasks/debug-application-cluster/debug-pod-replication-controller.md
	modified:   content/ja/docs/tasks/debug-application-cluster/debug-service.md
	modified:   content/ja/docs/tasks/debug-application-cluster/debug-stateful-set.md
	modified:   content/ja/docs/tasks/debug-application-cluster/determine-reason-pod-failure.md
	modified:   content/ja/docs/tasks/debug-application-cluster/get-shell-running-container.md
	modified:   content/ja/docs/tasks/inject-data-application/_index.md
	modified:   content/ja/docs/tasks/inject-data-application/define-environment-variable-container.md
	modified:   content/ja/docs/tasks/run-application/_index.md
	modified:   content/ja/docs/tasks/run-application/delete-stateful-set.md
	modified:   content/ja/docs/tasks/run-application/force-delete-stateful-set-pod.md
	new file:   content/ja/docs/tasks/run-application/horizontal-pod-autoscale-walkthrough.md
	modified:   content/ja/docs/tasks/run-application/run-replicated-stateful-application.md
	modified:   content/ja/docs/tasks/run-application/run-stateless-application-deployment.md
	modified:   content/ja/docs/tasks/service-catalog/install-service-catalog-using-helm.md
	modified:   content/ja/docs/tasks/service-catalog/install-service-catalog-using-sc.md
	modified:   content/ja/docs/tasks/tools/_index.md
	modified:   content/ja/docs/tasks/tools/install-kubectl.md
	deleted:    content/ja/docs/tasks/tools/install-minikube.md
	modified:   content/ja/docs/tutorials/_index.md
	modified:   content/ja/docs/tutorials/hello-minikube.md
	modified:   content/ja/docs/tutorials/kubernetes-basics/create-cluster/cluster-interactive.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/deploy-app/deploy-interactive.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/deploy-app/deploy-intro.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/explore/explore-interactive.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/explore/explore-intro.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/expose/expose-interactive.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/expose/expose-intro.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/scale/scale-interactive.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/scale/scale-intro.html
	modified:   content/ja/docs/tutorials/kubernetes-basics/update/update-interactive.html
	modified:   content/ja/docs/tutorials/services/source-ip.md
	modified:   content/ja/docs/tutorials/stateful-application/cassandra.md
	modified:   content/ja/docs/tutorials/stateful-application/mysql-wordpress-persistent-volume.md
	modified:   content/ja/docs/tutorials/stateless-application/expose-external-ip-address.md

いかがでしょう。

new fileとなっているものはv1.18より新しい内容をもとに翻訳されている可能性があるため、除外するのがよいかもしれません。

おわりに

「v1.18のドキュメントを参照するには、最新バージョンを選択してください」と伝えるのは心苦しい、また、近い将来v1.19に置き換わってしまう可能性があるため、うまいことバージョン管理したいところです。本提案で解決できるか、kubernetes-docs-ja-maintainersのみなさん、ご検討ください！