Introduce GREP template and a refactored TAS GREP (#362)

unmarshall · sanjaychatterjee · web-flow · commit ac9b7110ebe9 · 2026-01-24T10:33:45.000+05:30
* Introduced GREP template.
* Added sections on monitoring and PodGang API
* Added support for generating table of contents for GREPs
* Added support to verify if the table of contents are up to date.
* Added license headers to update-toc and verify-toc scripts
* Added verify-toc to check make target
* Added Alternatives section to TAS GREP

Signed-off-by: Madhav Bhargava &lt;madhav.bhargava@sap.com&gt;
Co-authored-by: Sanjay Chatterjee &lt;sanjay.chatterjee@gmail.com&gt;

---------

Signed-off-by: Madhav Bhargava &lt;madhav.bhargava@sap.com&gt;
Co-authored-by: Sanjay Chatterjee &lt;sanjay.chatterjee@gmail.com&gt;
diff --git a/Makefile b/Makefile
@@ -29,7 +29,7 @@ tidy:
 
 # Checks the entire codebase by linting and formatting the code base, and checking for uncommitted changes
 .PHONY: check
-check: generate add-license-headers format generate-api-docs lint
+check: generate add-license-headers format generate-api-docs lint verify-toc
 	@echo "> Checking for uncommitted changes"
 	@if [ -n "$$(git status --porcelain)" ]; then \
 		echo "ERROR: Git tree is dirty after running validation steps."; \
@@ -116,3 +116,13 @@ test-e2e:
 .PHONY: test
 test: test-unit test-envtest
 	@echo "> All tests passed"
+
+# Updates the docs/proposals table of contents
+.PHONY: update-toc
+update-toc: $(MDTOC)
+	@$(REPO_HACK_DIR)/update-toc.sh
+
+# Verifies that the docs/proposals table of contents is up to date
+.PHONY: verify-toc
+verify-toc: $(MDTOC)
+	@$(REPO_HACK_DIR)/verify-toc.sh
diff --git a/docs/designs/topology.md b/docs/designs/topology.md
diff --git a/docs/proposals/244-topology-aware-scheduling/README.md b/docs/proposals/244-topology-aware-scheduling/README.md
diff --git a/docs/proposals/244-topology-aware-scheduling/assets/tas-highlevel-architecture.excalidraw.excalidraw.png b/docs/proposals/244-topology-aware-scheduling/assets/tas-highlevel-architecture.excalidraw.excalidraw.png
diff --git a/docs/proposals/NNNN-template/README.md b/docs/proposals/NNNN-template/README.md
@@ -0,0 +1,145 @@
+# GREP-NNNN: Short descriptive title
+
+<!-- toc -->
+- [Summary](#summary)
+- [Motivation](#motivation)
+  - [Goals](#goals)
+  - [Non-Goals](#non-goals)
+- [Proposal](#proposal)
+  - [User Stories (<em>Optional</em>)](#user-stories-optional)
+    - [Story 1 (<em>Optional</em>)](#story-1-optional)
+    - [Story 2 (<em>Optional</em>)](#story-2-optional)
+  - [Limitations/Risks &amp; Mitigations](#limitationsrisks--mitigations)
+- [Design Details](#design-details)
+  - [Monitoring](#monitoring)
+  - [Dependencies (<em>Optional</em>)](#dependencies-optional)
+  - [Test Plan](#test-plan)
+  - [Graduation Criteria](#graduation-criteria)
+- [Implementation History (<em>Optional</em>)](#implementation-history-optional)
+- [Alternatives (<em>Optional</em>)](#alternatives-optional)
+- [Appendix (<em>Optional</em>)](#appendix-optional)
+<!-- /toc -->
+
+<!--
+Include a table of contents as it helps to navigate easily in the document.
+
+Ensure the TOC is wrapped with
+   <code>&lt;!-- toc --&gt;&lt;!-- /toc --&gt;</code>
+tags, and then generate by invoking the make target `update-toc`.
+
+-->
+
+## Summary
+
+<!--
+This section should contain user-focused documentation such as release notes or a development roadmap. It should also have a summary of functional increment that is being introduced as part of this GREP. A good summary should address a wider audience and should ideally be a single paragraph.
+-->
+
+## Motivation
+
+<!-- 
+This section explicitly lists the motivation which consists of goals and the non-goals of this GREP. Use this section to describe why the change introduced in this GREP is important and what benefits it brings to the users.
+-->
+
+### Goals
+
+<!-- 
+Lists specific goals of this GREP. What is it trying to achieve.
+-->
+
+### Non-Goals
+
+<!-- 
+Lists what all is out of scope of this GREP. Listing non-goals helps to clearly define the scope within which the discussions should happen.
+-->
+
+## Proposal
+
+<!-- 
+Contains the specifics of the proposal. Sufficient details should be provided to help reviewers clearly understand the proposal. It should not include API design, low level design and implementation details which should be mentioned under 'Design Details' section instead.
+-->
+
+### User Stories (*Optional*)
+
+<!-- 
+This section provides detailed use cases descibing how changes introduced in this GREP are going to be used. The intent is to carve out real-world scenarios which serve as additional motivation providing clarity/context for the changes proposed.
+-->
+
+#### Story 1 (*Optional*)
+
+#### Story 2 (*Optional*)
+
+### Limitations/Risks & Mitigations
+
+<!-- 
+What are the current set of limitations or risks of this proposal? Think broadly by considering the impact of the changes proposed on kubernetes ecosystem. Optionally mention ways to mitigate these.
+-->
+
+## Design Details
+
+<!-- 
+This section may include API specifications (GO API/YAML) and certain flow control diagrams that will help reviewers to know how the proposal will be implemented.
+-->
+
+### Monitoring
+
+<!--
+This section contains details of events, metrics, status conditions and other status fields that will aid in determining health of the feature, or help measure any service level objectives that might be optionally defined.
+-->
+
+### Dependencies (*Optional*)
+
+<!--
+Are there any dependencies for this feature to work? If yes then those should be clearly listed with optional links on how to ensure that the dependencies are setup.
+-->
+
+### Test Plan
+
+<!--
+For the functionality an epic (issue) should be created. Along with a sub-issue for the GREP, there should be a dedicated issue created for integration and e2e tests. This issue should have details of all scenarios that needs to be tested. Provide a link to issue(s) in this section.
+-->
+
+### Graduation Criteria
+
+<!-- 
+In this section graduation milestones should be defined. The progression of the overall feature can be evaluated w.r.t API maturity, staged sub-feature implementation or some other criteria.
+
+In general we try to use the same stages (alpha, beta, GA), regardless of how the
+functionality is accessed. Refer to these for more details:"
+
+* [Feature Gates](https://git.k8s.io/community/contributors/devel/sig-architecture/feature-gates.md)
+* [Maturity levels](https://git.k8s.io/community/contributors/devel/sig-architecture/api_changes.md#alpha-beta-and-stable-versions)
+* [Deprecation Policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/ ) 
+
+**Note:** Generally we also wait at least two releases between beta and
+GA/stable, because there's no opportunity for user feedback, or even bug reports,
+in back-to-back releases. 
+-->
+
+## Implementation History (*Optional*)
+
+<!--
+Major milestones in the lifecycle of a GREP should be tracked in this section.
+Major milestones might include:
+
+- The date proposal was accepted and merged.
+- The date implementation started.
+- The date of Alpha release for the feature.
+- The date the feature graduated to beta/GA
+
+-->
+
+## Alternatives (*Optional*)
+
+<!--
+What are the alternative approaches considered and reasons to rule those out. This section should have sufficient details (not too much) to express the alternative idea and why it was not accepted.
+-->
+
+## Appendix (*Optional*)
+
+<!-- 
+Use this section to put any prerequisite reading links or helpful information/data that supplements the proposal, thus providing additional context to the reviewer.
+-->
+
+> NOTE: This GREP template has been inspired by [KEP Template](https://github.com/kubernetes/enhancements/blob/f90055d254c356b2c038a1bdf4610bf4acd8d7be/keps/NNNN-kep-template/README.md).
+
diff --git a/docs/proposals/README.md b/docs/proposals/README.md
@@ -0,0 +1,18 @@
+# Grove Enhancement Proposal (GREP)
+
+A Grove Enhancement Proposal (GREP) is a structure way to suggest improvements, new features or changes to Grove. It helps you to clearly explain the proposed change(s) conceptually, and to outline the concrete steps needed to reach this goal. It helps the Grove maintainers as well as the community to understand the motivation and scope around your proposed change(s) and encourages their contribution to discussions and future pull requests.
+
+## How to file a GREP
+
+GREPs should be created as Markdown `.md` files and should be submitted for review via Github pull request. Please follow the following rules:
+* It is mandatory to create a tracking issue [here](https://github.com/ai-dynamo/grove/issues) whose issue number will also be used as the GREP number.
+* All GREPs should have an appropriately named directory under `docs/proposals`. The GREP's file name should be `README.md` to be consistent.
+* Use the GREP template at `docs/proposals/NNNN-template/README.md`
+* Ensure that you always generate the table of contents. Use the make target `make update-toc`.
+* You can locally verify if the table of contents for your GREP are up-to-date by running `make verify-toc`.
+
+> NOTE: GREP is heavily inspired from Kubernetes KEP template.
+
+### What is the number at the beginning of the GREP name?
+
+GREPs are prefixed with their associated tracking issue number. This gives both the GREP a unique identifier and provides an easy breadcrumb for people to find the issue where the current state of the GREP is being updated.
diff --git a/hack/.notableofcontents b/hack/.notableofcontents
@@ -0,0 +1 @@
+docs/proposals/README.md
diff --git a/hack/tools.mk b/hack/tools.mk
@@ -27,6 +27,7 @@ YQ                := $(TOOLS_BIN_DIR)/yq
 GO_ADD_LICENSE    := $(TOOLS_BIN_DIR)/addlicense
 SKAFFOLD          := $(TOOLS_BIN_DIR)/skaffold
 CRD_REF_DOCS      := $(TOOLS_BIN_DIR)/crd-ref-docs
+MDTOC			  := $(TOOLS_BIN_DIR)/mdtoc
 
 # default tool versions
 # -------------------------------------------------------------------------
@@ -38,6 +39,7 @@ YQ_VERSION                ?= v4.48.1
 GO_ADD_LICENSE_VERSION    ?= v1.2.0
 SKAFFOLD_VERSION          ?= v2.16.1
 CRD_REF_DOCS_VERSION      ?= v0.2.0
+MDTOC_VERSION             ?= latest
 
 export PATH := $(abspath $(TOOLS_BIN_DIR)):$(PATH)
 
@@ -85,4 +87,7 @@ $(SKAFFOLD):
 	chmod +x $(SKAFFOLD)
 
 $(CRD_REF_DOCS):
-	GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install github.com/elastic/crd-ref-docs@$(CRD_REF_DOCS_VERSION)
+	GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install github.com/elastic/crd-ref-docs@$(CRD_REF_DOCS_VERSION)
+
+$(MDTOC):
+	GOBIN=$(abspath $(TOOLS_BIN_DIR)) go install sigs.k8s.io/mdtoc@latest
diff --git a/hack/update-toc.sh b/hack/update-toc.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+# /*
+# Copyright 2026 The Grove 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
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+REPO_ROOT="$(dirname $SCRIPT_DIR)"
+
+echo "> Updating table of contents for docs/proposals..."
+
+# Process each markdown file individually
+while IFS= read -r file; do
+  # Convert to relative path for exclusion check
+  rel_path="${file#${REPO_ROOT}/}"
+
+  # Check if file should be excluded
+  if grep -Fxq "${rel_path}" "${SCRIPT_DIR}/.notableofcontents" 2>/dev/null; then
+    echo "⊘ Excluded: ${rel_path}"
+    continue
+  fi
+
+
+  # Create a temporary copy to compare against
+  temp_file=$(mktemp)
+  cp "${file}" "${temp_file}"
+
+  # Run mdtoc on the file
+  if mdtoc --inplace --max-depth=6 "${file}" 2>/dev/null; then
+    # Compare to see if anything changed
+    if diff -q "${temp_file}" "${file}" >/dev/null 2>&1; then
+      echo "✓ Unchanged: ${rel_path}"
+    else
+      echo "✓ Updated: ${rel_path}"
+    fi
+  else
+    echo "✗ Failed: ${rel_path}"
+    rm -f "${temp_file}"
+    exit 1
+  fi
+
+  rm -f "${temp_file}"
+
+done < <(find "${REPO_ROOT}/docs/proposals" -name '*.md' -type f | sort)
diff --git a/hack/verify-toc.sh b/hack/verify-toc.sh
@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# /*
+# Copyright 2026 The Grove 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
+
+SCRIPT_DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )"
+REPO_ROOT="$(dirname $SCRIPT_DIR)"
+
+echo "> Verifying if table of contents for docs/proposals are up-to-date..."
+
+find ${REPO_ROOT}/docs/proposals -name '*.md' \
+  | sed "s|^${REPO_ROOT}/||" \
+  | grep -Fxvf "${SCRIPT_DIR}/.notableofcontents" \
+  | sed "s|^|${REPO_ROOT}/|" \
+  | xargs mdtoc --inplace --max-depth=6 --dryrun || (
+    echo "Table of content not up to date. Did you run 'make update-toc' ?"
+    exit 1
+  )
