From aa5dc3c1ddd81b48eedbcd130e913ec9231c8d6a Mon Sep 17 00:00:00 2001
From: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
Date: Fri, 17 Apr 2026 14:02:15 +0500
Subject: [PATCH 1/2] [docs] Add a design proposal template
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds design-proposals/template.md as the starting point for new
proposals. Sections follow a narrative order reviewers can read
top-down: metadata → overview → scope/context → goals → design →
consequences (user-facing changes, upgrade/rollback, security,
failure cases) → testing → rollout → open questions → alternatives.

Each section has a short HTML comment explaining what belongs in it
and what to omit. Alternatives sits at the end so reviewers can
evaluate rejected options against the already-described design.

Proposed as an alternative to #3.

Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
---
 design-proposals/template.md | 102 +++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)
 create mode 100644 design-proposals/template.md

diff --git a/design-proposals/template.md b/design-proposals/template.md
new file mode 100644
index 0000000..d7cdd84
--- /dev/null
+++ b/design-proposals/template.md
@@ -0,0 +1,102 @@
+# Your proposal title
+
+- **Title:** `Your full title`
+- **Author(s):** `@your-github-handle, @coauthor`
+- **Date:** `YYYY-MM-DD`
+- **Status:** Draft | Review | Accepted | Superseded
+
+<!-- Status transitions: Draft → Review (PR opened) → Accepted (merged)
+     or Superseded (replaced by a later proposal; link it). -->
+
+## Overview
+
+<!-- One or two paragraphs. What are you proposing, and why, in plain words?
+A reader who stops here should know what you're asking for and roughly why. -->
+
+## Scope and related proposals
+
+<!-- Sibling or follow-up proposals and anything deliberately deferred.
+Link them by repo path or URL. If this proposal must land before or after
+another, say so. Omit the section if there are no related proposals. -->
+
+## Context
+
+<!-- Background a reader needs to evaluate the proposal.
+What does the system do today? Which files/components are relevant?
+Link to them by repo path; do not assume the reader has your tab open. -->
+
+### The problem
+
+<!-- Concrete pain, ideally in the user's voice.
+Scenarios that are broken or awkward today. -->
+
+## Goals
+
+<!-- What success looks like. Bullet list; each bullet should be testable. -->
+
+### Non-goals
+
+<!-- What this proposal explicitly does not do. Protects the scope from
+review-time drift. -->
+
+## Design
+
+<!-- The core of the proposal. Break into numbered or titled subsections
+as needed (data model, API, schema changes, template changes, controller
+changes, etc.). Show before/after for shapes that are changing. Include
+code blocks (YAML, gotemplate, Go) where prose would be ambiguous.
+Diagrams: Mermaid.js renders on GitHub. -->
+
+## User-facing changes
+
+<!-- What admins / tenants / operators will see: CLI, dashboard, CRD shape,
+docs entry point. If there is no user-facing change, say so. -->
+
+## Upgrade and rollback compatibility
+
+<!-- Will existing clusters, manifests, or APIs keep working?
+Is a migration required? Automatic or manual?
+What's the rollback story if the feature is reverted?
+If the change is irreversible once applied, flag it here. -->
+
+## Security
+
+<!-- New trust boundaries, new tenant-supplied inputs, new RBAC surface,
+new secrets stored or transmitted. If none, say so explicitly. -->
+
+## Failure and edge cases
+
+<!-- Concrete scenarios and expected behavior, one bullet each.
+Examples:
+- Invalid input X → chart rejects; Flux surfaces the error on status.
+- Migration runs twice → idempotent; no-op on the second run. -->
+
+## Testing
+
+<!-- How this will be validated. Be specific about which layer
+(unit / integration / e2e / manual) and what is asserted. -->
+
+## Rollout
+
+<!-- Ordered releases or phases. Which release ships what.
+What gets deprecated in which release. -->
+
+## Open questions
+
+<!-- Unresolved design points you want reviewer input on.
+Close these out or fold them into the body before the proposal is accepted. -->
+
+## Alternatives considered
+
+<!-- For each alternative, one short paragraph: what it is, why it was rejected.
+Group by dimension (data model, runtime mechanism, schema approach, etc.)
+when you evaluated options along multiple axes. Prevents reviewers from
+re-litigating options you already dismissed. -->
+
+---
+
+<!--
+Inspired by KubeVirt enhancement proposals
+(https://github.com/kubevirt/enhancements) and Kubernetes Enhancement
+Proposals (KEPs).
+-->

From 657fe1a3a13da1f01c182adc4dfbe007e3690ad0 Mon Sep 17 00:00:00 2001
From: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
Date: Fri, 17 Apr 2026 16:33:52 +0500
Subject: [PATCH 2/2] [docs] Address review feedback on proposal template

- Add a top-of-file comment reminding authors to rename to README.md
  and place it in a sub-directory under design-proposals/.
- Add Rejected as a status state and include it in the transitions
  comment.

Signed-off-by: Myasnikov Daniil <myasnikovdaniil2001@gmail.com>
---
 design-proposals/template.md | 7 ++++---
 1 file changed, 4 insertions(+), 3 deletions(-)

diff --git a/design-proposals/template.md b/design-proposals/template.md
index d7cdd84..176743a 100644
--- a/design-proposals/template.md
+++ b/design-proposals/template.md
@@ -1,12 +1,13 @@
+<!-- Rename this file to README.md and place it in a sub-directory under design-proposals/ -->
 # Your proposal title
 
 - **Title:** `Your full title`
 - **Author(s):** `@your-github-handle, @coauthor`
 - **Date:** `YYYY-MM-DD`
-- **Status:** Draft | Review | Accepted | Superseded
+- **Status:** Draft | Review | Accepted | Rejected | Superseded
 
-<!-- Status transitions: Draft → Review (PR opened) → Accepted (merged)
-     or Superseded (replaced by a later proposal; link it). -->
+<!-- Status transitions: Draft → Review (PR opened) → Accepted (merged),
+     Rejected, or Superseded (replaced by a later proposal; link it). -->
 
 ## Overview