Automatically synchronize FGs and documentation FGs list

vladikkuzn · vladikkuzn · commit f2bbb232bf58 · 2025-11-27T03:36:03.000+02:00
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -25,3 +25,21 @@ If your repo has certain guidelines for contribution, put them here ahead of the
 
 - [Slack](https://kubernetes.slack.com/messages/sig-scheduling)
 - [Mailing List](https://groups.google.com/forum/#!forum/kubernetes-sig-scheduling)
+
+## Feature gate documentation workflow
+
+Kueue treats `pkg/features/kube_features.go` as the source of truth for every feature gate. After you change that file, run:
+
+```shell
+make featuregates-update
+```
+
+This command uses Kubernetes' `compatibility_lifecycle` tool to regenerate `test/compatibility_lifecycle/reference/versioned_feature_list.yaml` and copies the result to `site/data/featuregates/versioned_feature_list.yaml`. The docs under `site/content/*/docs/installation/_index.md` consume that YAML through the `feature-gates-table` shortcode, so no manual table edits are required.
+
+CI enforces that the YAML and documentation stay in sync. You can run the same check locally with:
+
+```shell
+make featuregates-verify
+```
+
+or simply rely on `make verify`, which now calls the verification target automatically.
diff --git a/Makefile b/Makefile
@@ -183,6 +183,16 @@ toc-update: mdtoc
 toc-verify: mdtoc
 	./hack/verify-toc.sh
 
+##@ Documentation
+
+.PHONY: featuregates-update
+featuregates-update: ## Regenerate feature-gate YAML and site data.
+	$(PROJECT_DIR)/hack/update-featuregates.sh
+
+.PHONY: featuregates-verify
+featuregates-verify: ## Ensure feature-gate YAML and docs are in sync.
+	$(PROJECT_DIR)/hack/verify-featuregates.sh
+
 .PHONY: helm-lint
 helm-lint: helm ## Run Helm chart lint test.
 	${HELM} lint charts/kueue
@@ -262,7 +272,7 @@ sync-hugo-version:
 
 PATHS_TO_VERIFY := config/components apis charts/kueue client-go site/ netlify.toml
 .PHONY: verify
-verify: gomod-verify ci-lint lint-api fmt-verify shell-lint toc-verify manifests generate update-helm helm-verify helm-unit-test prepare-release-branch sync-hugo-version npm-depcheck
+verify: gomod-verify ci-lint lint-api fmt-verify shell-lint toc-verify featuregates-verify manifests generate update-helm helm-verify helm-unit-test prepare-release-branch sync-hugo-version npm-depcheck
 	git --no-pager diff --exit-code $(PATHS_TO_VERIFY)
 	if git ls-files --exclude-standard --others $(PATHS_TO_VERIFY) | grep -q . ; then exit 1; fi
 
diff --git a/hack/update-featuregates.sh b/hack/update-featuregates.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+
+# Copyright 2024 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MOD_FILE="${REPO_ROOT}/hack/tools/go.mod"
+K8S_TOOL_PKG="k8s.io/kubernetes/test/compatibility_lifecycle"
+REFERENCE_DIR="${REPO_ROOT}/test/compatibility_lifecycle/reference"
+REFERENCE_FILE="${REFERENCE_DIR}/versioned_feature_list.yaml"
+SITE_DATA_DIR="${REPO_ROOT}/site/data/featuregates"
+SITE_DATA_FILE="${SITE_DATA_DIR}/versioned_feature_list.yaml"
+
+mkdir -p "${REFERENCE_DIR}"
+mkdir -p "${SITE_DATA_DIR}"
+
+go run -mod=mod -modfile="${MOD_FILE}" "${K8S_TOOL_PKG}" feature-gates update
+
+cp "${REFERENCE_FILE}" "${SITE_DATA_FILE}"
+
diff --git a/hack/verify-featuregates.sh b/hack/verify-featuregates.sh
@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+
+# Copyright 2024 The Kubernetes Authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+set -o errexit
+set -o nounset
+set -o pipefail
+
+REPO_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+MOD_FILE="${REPO_ROOT}/hack/tools/go.mod"
+K8S_TOOL_PKG="k8s.io/kubernetes/test/compatibility_lifecycle"
+REFERENCE_FILE="${REPO_ROOT}/test/compatibility_lifecycle/reference/versioned_feature_list.yaml"
+SITE_DATA_FILE="${REPO_ROOT}/site/data/featuregates/versioned_feature_list.yaml"
+
+if [[ ! -f "${REFERENCE_FILE}" ]]; then
+  echo "missing reference file: ${REFERENCE_FILE}" >&2
+  exit 1
+fi
+
+if ! go run -mod=mod -modfile="${MOD_FILE}" "${K8S_TOOL_PKG}" feature-gates verify; then
+  echo "Please run 'hack/update-featuregates.sh' to regenerate feature gates." >&2
+  exit 1
+fi
+
+if ! cmp -s "${REFERENCE_FILE}" "${SITE_DATA_FILE}"; then
+  echo "Feature-gate YAML under site/data/featuregates is out of sync. Re-run hack/update-featuregates.sh." >&2
+  exit 1
+fi
+
diff --git a/site/content/en/docs/installation/_index.md b/site/content/en/docs/installation/_index.md
@@ -280,47 +280,7 @@ spec:
 
 ### Feature gates for alpha and beta features
 
-| Feature                                       | Default | Stage | Since | Until |
-| --------------------------------------------- | ------- | ----- | ----- | ----- |
-| `FlavorFungibility`                           | `true`  | Beta  | 0.5   |       |
-| `MultiKueue`                                  | `false` | Alpha | 0.6   | 0.8   |
-| `MultiKueue`                                  | `true`  | Beta  | 0.9   |       |
-| `MultiKueueBatchJobWithManagedBy`             | `false` | Alpha | 0.8   | 0.15  |
-| `MultiKueueBatchJobWithManagedBy`             | `true`  | Beta  | 0.15  |       |
-| `PartialAdmission`                            | `false` | Alpha | 0.4   | 0.4   |
-| `PartialAdmission`                            | `true`  | Beta  | 0.5   |       |
-| `VisibilityOnDemand`                          | `false` | Alpha | 0.6   | 0.8   |
-| `VisibilityOnDemand`                          | `true`  | Beta  | 0.9   |       |
-| `PrioritySortingWithinCohort`                 | `true`  | Beta  | 0.6   |       |
-| `LendingLimit`                                | `false` | Alpha | 0.6   | 0.8   |
-| `LendingLimit`                                | `true`  | Beta  | 0.9   |       |
-| `TopologyAwareScheduling`                     | `false` | Alpha | 0.9   | 0.13  |
-| `TopologyAwareScheduling`                     | `true`  | Beta  | 0.14  |       |
-| `LocalQueueDefaulting`                        | `false` | Alpha | 0.10  | 0.11  |
-| `LocalQueueDefaulting`                        | `true`  | Beta  | 0.12  |       |
-| `LocalQueueMetrics`                           | `false` | Alpha | 0.10  |       |
-| `HierarchicalCohort`                          | `true`  | Beta  | 0.11  |       |
-| `ObjectRetentionPolicies`                     | `false` | Alpha | 0.12  | 0.12  |
-| `ObjectRetentionPolicies`                     | `true`  | Beta  | 0.13  |       |
-| `TASFailedNodeReplacement`                    | `false` | Alpha | 0.12  | 0.13  |
-| `TASFailedNodeReplacement`                    | `true`  | Beta  | 0.14  |       |
-| `AdmissionFairSharing`                        | `false` | Alpha | 0.12  |       |
-| `AdmissionFairSharing`                        | `true`  | Beta  | 0.15  |       |
-| `TASFailedNodeReplacementFailFast`            | `false` | Alpha | 0.12  | 0.13  |
-| `TASFailedNodeReplacementFailFast`            | `true`  | Beta  | 0.14  |       |
-| `TASReplaceNodeOnPodTermination`              | `false` | Alpha | 0.13  | 0.13  |
-| `TASReplaceNodeOnPodTermination`              | `true`  | Beta  | 0.14  |       |
-| `ElasticJobsViaWorkloadSlices`                | `false` | Alpha | 0.13  |       |
-| `ManagedJobsNamespaceSelectorAlwaysRespected` | `false` | Alpha | 0.13  | 0.15  |
-| `ManagedJobsNamespaceSelectorAlwaysRespected` | `true`  | Beta  | 0.15  |       |
-| `FlavorFungibilityImplicitPreferenceDefault`  | `false` | Alpha | 0.13  | 0.16  |
-| `WorkloadRequestUseMergePatch`                | `false` | Alpha | 0.14  |       |
-| `SanitizePodSets`                             | `true`  | Beta  | 0.13  |       |
-| `MultiKueueAllowInsecureKubeconfigs`          | `false` | Alpha | 0.13  |       |
-| `ReclaimablePods`                             | `true`  | Beta  | 0.15  |       |
-| `MultiKueueAdaptersForCustomJobs`             | `false` | Alpha | 0.14  | 0.14  |
-| `MultiKueueAdaptersForCustomJobs`             | `true`  | Beta  | 0.15  |       |
-| `PropagateBatchJobLabelsToWorkload`           | `true`  | Beta  | 0.15  |       |
+{{< feature-gates-table stage="alpha-beta" >}}
 
 {{% alert title="Note" color="primary" %}}
 The SanitizePodSets and MultiKueueAllowInsecureKubeconfigs features are available starting from versions 0.13.8 and 0.14.3.
@@ -329,14 +289,7 @@ The PropagateBatchJobLabelsToWorkload feature is available starting from version
 
 ### Feature gates for graduated or deprecated features
 
-| Feature                               | Default | Stage      | Since | Until |
-| ------------------------------------- | ------- | ---------- | ----- | ----- |
-| `ConfigurableResourceTransformations` | `false` | Alpha      | 0.9   | 0.9   |
-| `ConfigurableResourceTransformations` | `true`  | Beta       | 0.10  | 0.13  |
-| `ConfigurableResourceTransformations` | `true`  | GA         | 0.14  |       |
-| `TASProfileMostFreeCapacity`          | `false` | Deprecated | 0.11  | 0.13  |
-| `TASProfileLeastFreeCapacity`         | `false` | Deprecated | 0.11  |       |
-| `TASProfileMixed`                     | `false` | Deprecated | 0.11  |       |
+{{< feature-gates-table stage="ga-deprecated" >}}
 
 ## What's next
 
diff --git a/site/content/zh-CN/docs/installation/_index.md b/site/content/zh-CN/docs/installation/_index.md
@@ -262,54 +262,11 @@ spec:
 
 ### Alpha 和 Beta 级别特性的特性门控 {#feature-gates-for-alpha-and-beta-features}
 
-| 功能                                            | 默认值     | 阶段    | 起始版本 | 截止版本 |
-|-----------------------------------------------|---------|-------|------|------|
-| `FlavorFungibility`                           | `true`  | Beta  | 0.5  |      |
-| `MultiKueue`                                  | `false` | Alpha | 0.6  | 0.8  |
-| `MultiKueue`                                  | `true`  | Beta  | 0.9  |      |
-| `MultiKueueBatchJobWithManagedBy`             | `false` | Alpha | 0.8  | 0.15 |
-| `MultiKueueBatchJobWithManagedBy`             | `true`  | Beta  | 0.15 |      |
-| `PartialAdmission`                            | `false` | Alpha | 0.4  | 0.4  |
-| `PartialAdmission`                            | `true`  | Beta  | 0.5  |      |
-| `VisibilityOnDemand`                          | `false` | Alpha | 0.6  | 0.8  |
-| `VisibilityOnDemand`                          | `true`  | Beta  | 0.9  |      |
-| `PrioritySortingWithinCohort`                 | `true`  | Beta  | 0.6  |      |
-| `LendingLimit`                                | `false` | Alpha | 0.6  | 0.8  |
-| `LendingLimit`                                | `true`  | Beta  | 0.9  |      |
-| `TopologyAwareScheduling`                     | `false` | Alpha | 0.9  | 0.13 |
-| `TopologyAwareScheduling`                     | `true`  | Beta  | 0.14 |      |
-| `LocalQueueDefaulting`                        | `false` | Alpha | 0.10 | 0.11 |
-| `LocalQueueDefaulting`                        | `true`  | Beta  | 0.12 |      |
-| `LocalQueueMetrics`                           | `false` | Alpha | 0.10 |      |
-| `HierarchicalCohort`                          | `true`  | Beta  | 0.11 |      |
-| `ObjectRetentionPolicies`                     | `false` | Alpha | 0.12 | 0.12 |
-| `ObjectRetentionPolicies`                     | `true`  | Beta  | 0.13 |      |
-| `TASFailedNodeReplacement`                    | `false` | Alpha | 0.12 | 0.13 |
-| `TASFailedNodeReplacement`                    | `true`  | Beta  | 0.14 |      |
-| `AdmissionFairSharing`                        | `false` | Alpha | 0.12 |      |
-| `TASFailedNodeReplacementFailFast`            | `false` | Alpha | 0.12 | 0.13 |
-| `TASFailedNodeReplacementFailFast`            | `true`  | Beta  | 0.14 |      |
-| `TASReplaceNodeOnPodTermination`              | `false` | Alpha | 0.13 | 0.13 |
-| `TASReplaceNodeOnPodTermination`              | `true`  | Beta  | 0.14 |      |
-| `ElasticJobsViaWorkloadSlices`                | `false` | Alpha | 0.13 |      |
-| `ManagedJobsNamespaceSelectorAlwaysRespected` | `false` | Alpha | 0.13 |      |
-| `FlavorFungibilityImplicitPreferenceDefault`  | `false` | Alpha | 0.13 | 0.16 |
-| `WorkloadRequestUseMergePatch`                | `false` | Alpha | 0.14 |      |
-| `SanitizePodSets`                             | `true`  | Beta  | 0.13 |      |
-| `MultiKueueAllowInsecureKubeconfigs`          | `false` | Alpha | 0.13 |      |
+{{< feature-gates-table stage="alpha-beta" >}}
 
 ### 已毕业或已弃用特性的特性门控 {#feature-gates-for-graduated-or-deprecated-features}
 
-| 功能                                    | 默认值     | 阶段         | 起始版本 | 截止版本 |
-|---------------------------------------|---------|------------|------|------|
-| `ManagedJobsNamespaceSelector`        | `true`  | Beta       | 0.10 | 0.13 |
-| `ManagedJobsNamespaceSelector`        | `true`  | GA         | 0.13 |      |
-| `ConfigurableResourceTransformations` | `false` | Alpha      | 0.9  | 0.9  |
-| `ConfigurableResourceTransformations` | `true`  | Beta       | 0.10 | 0.13 |
-| `ConfigurableResourceTransformations` | `true`  | GA         | 0.14 |      |
-| `TASProfileMostFreeCapacity`          | `false` | Deprecated | 0.11 | 0.13 |
-| `TASProfileLeastFreeCapacity`         | `false` | Deprecated | 0.11 |      |
-| `TASProfileMixed`                     | `false` | Deprecated | 0.11 |      |
+{{< feature-gates-table stage="ga-deprecated" >}}
 
 ## 接下来是什么 {#whats-next}
 
diff --git a/site/data/featuregates/versioned_feature_list.yaml b/site/data/featuregates/versioned_feature_list.yaml
diff --git a/site/layouts/shortcodes/feature-gates-table.html b/site/layouts/shortcodes/feature-gates-table.html
diff --git a/test/compatibility_lifecycle/reference/versioned_feature_list.yaml b/test/compatibility_lifecycle/reference/versioned_feature_list.yaml
