From 41da7497c383a797309924e631b7ddb2be8221b6 Mon Sep 17 00:00:00 2001
From: Jan Chaloupka <jchaloup@redhat.com>
Date: Mon, 15 Dec 2025 21:06:39 +0100
Subject: [PATCH] doc: introduce contributing guidelines specific to the
 project

The document is to be extended on the fly
---
 CONTRIBUTING-descheduler.md | 22 ++++++++++++++++++++++
 1 file changed, 22 insertions(+)
 create mode 100644 CONTRIBUTING-descheduler.md

diff --git a/CONTRIBUTING-descheduler.md b/CONTRIBUTING-descheduler.md
new file mode 100644
index 000000000..835c1a90d
--- /dev/null
+++ b/CONTRIBUTING-descheduler.md
@@ -0,0 +1,22 @@
+# Descheduler Design Constraints
+
+This is a slowly growing document that lists good practices, conventions, and design decisions.
+
+## Overview
+
+TBD
+
+## Code convention
+
+* *formatting code*: running `make fmt` before committing each change to avoid ci failing
+
+## Unit Test Conventions
+
+These are the known conventions that are useful to practice whenever reasonable:
+
+* *single pod creation*: each pod variable built using `test.BuildTestPod` is updated only through the `apply` argument of `BuildTestPod`
+* *single node creation*: each node variable built using `test.BuildTestNode` is updated only through the `apply` argument of `BuildTestNode`
+* *no object instance sharing*: each object built through `test.BuildXXX` functions is newly created in each unit test to avoid accidental object mutations
+* *no object instance duplication*: avoid duplication by no creating two objects with the same passed values at two different places. E.g. two nodes created with the same memory, cpu and pods requests. Rather create a single function wrapping test.BuildTestNode and invoke this wrapper multiple times.
+
+The aim is to reduce cognitive load when reading and debugging the test code.