From 6a9cefbaf39511d7200f8d5e1ac5c4cda3a1f760 Mon Sep 17 00:00:00 2001
From: Timo Behrendt <t.behrendt@t00n.de>
Date: Sat, 16 May 2026 20:12:43 +0200
Subject: [PATCH] update docs

---
 .vscode/launch.json |  3 ---
 README.md           | 16 ++++++++++++++++
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/.vscode/launch.json b/.vscode/launch.json
index edadf84..07a489e 100644
--- a/.vscode/launch.json
+++ b/.vscode/launch.json
@@ -1,7 +1,4 @@
 {
-  // Use IntelliSense to learn about possible attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
     {
diff --git a/README.md b/README.md
index 352e121..df09558 100644
--- a/README.md
+++ b/README.md
@@ -39,3 +39,19 @@ The ProxyProvider will be created in Authentik, but will not be assigned to an o
 ## Versioning
 
 As soon as the operator covers an entire use case, the version will be raised to v1 and follow default versioning rules. Before that, the version will be v1alpha1.
+
+## Development
+
+### Guidelines & Tips
+
+- Only do a single reconciliation at a time and then return.
+  - This is because your references from the k8s API get stale after each update.
+  - Whenever you update a resource, k8s API will send a new event to your controller, which will trigger a new reconciliation.
+- The API will periodically send a resource to the controller for re-syncing, giving the controller a chance to reconcile the state with the outside world.
+- Use finalizers to ensure that the controller gets a chance to reconcile the state with the outside world before the object is deleted. If no finalizer is present, the object is deleted immediately without the controller seeing it.
+- Use the resource's state to keep track of the current state of the outside world, e.g. identifiers of external resources, etc.
+
+### References
+
+- [Extend Kubernetes](https://kubernetes.io/docs/concepts/extend-kubernetes/#api-extensions)
+- [Example Controller Implementation](https://github.com/kubernetes/sample-controller)