From afb3e7a76b65c4e94f2b0401e750a07e7cff61a9 Mon Sep 17 00:00:00 2001
From: YuviPanda <yuvipanda@gmail.com>
Date: Wed, 22 Jul 2026 13:17:18 -0700
Subject: [PATCH 1/3] Add a document of 'tips' on designing with traitlets

The Jupyter ecosystem uses traitlets a lot, but there's not
a lot of 'design documentation' that tells you how to design
your applications to use traitlets. This is the start that at
least provides a collection of tips for folks
---
 docs/source/index.rst |  1 +
 docs/source/tips.md   | 50 +++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 51 insertions(+)
 create mode 100644 docs/source/tips.md

diff --git a/docs/source/index.rst b/docs/source/index.rst
index e1979dac7..235c1cf86 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,6 +23,7 @@ the configuration machinery.
     trait_types
     defining_traits
     api
+    tips
     config
     config-api
     utils
diff --git a/docs/source/tips.md b/docs/source/tips.md
new file mode 100644
index 000000000..71221a74d
--- /dev/null
+++ b/docs/source/tips.md
@@ -0,0 +1,50 @@
+# Tips for using Traitlets
+
+A collection of useful design tips for using traitlets in your
+application or library.
+
+## Avoid using "pure config" objects
+
+Put your traitlets config directly on the classes that are doing the work,
+rather than creating separate classes just for holding configuration. This
+keeps configuration close to the code it is configuring, and helps with
+discoverability as well.
+
+So instead of:
+
+```python
+class SpawnerConfig(LoggingConfigurable):
+    some_config = Unicode(
+        "",
+        config=True
+    )
+
+    some_other_config = Unicode(
+        "default",
+        config=True
+    )
+
+class Spawner:
+    def spawn(self, config: SpawnerConfig):
+        print(config.some_config)
+        # Do things with config
+
+```
+
+Prefer:
+
+```python
+class Spawner(LoggingConfigurable):
+    some_config = Unicode(
+        "",
+        config=True
+    )
+
+    some_other_config = Unicode(
+        "default",
+        config=True
+    )
+
+    def spawn(self):
+        print(self.some_config)
+```
\ No newline at end of file

From cb23d119be3baa1badbc0257d6d9e47206a242ef Mon Sep 17 00:00:00 2001
From: "pre-commit-ci[bot]"
 <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Date: Wed, 22 Jul 2026 20:21:09 +0000
Subject: [PATCH 2/3] style: pre-commit fixes

---
 docs/source/tips.md | 24 ++++++------------------
 1 file changed, 6 insertions(+), 18 deletions(-)

diff --git a/docs/source/tips.md b/docs/source/tips.md
index 71221a74d..0fcc58d56 100644
--- a/docs/source/tips.md
+++ b/docs/source/tips.md
@@ -14,37 +14,25 @@ So instead of:
 
 ```python
 class SpawnerConfig(LoggingConfigurable):
-    some_config = Unicode(
-        "",
-        config=True
-    )
+    some_config = Unicode("", config=True)
+
+    some_other_config = Unicode("default", config=True)
 
-    some_other_config = Unicode(
-        "default",
-        config=True
-    )
 
 class Spawner:
     def spawn(self, config: SpawnerConfig):
         print(config.some_config)
         # Do things with config
-
 ```
 
 Prefer:
 
 ```python
 class Spawner(LoggingConfigurable):
-    some_config = Unicode(
-        "",
-        config=True
-    )
+    some_config = Unicode("", config=True)
 
-    some_other_config = Unicode(
-        "default",
-        config=True
-    )
+    some_other_config = Unicode("default", config=True)
 
     def spawn(self):
         print(self.some_config)
-```
\ No newline at end of file
+```

From d15b84a3436421319558678cd7f1888005e14d8a Mon Sep 17 00:00:00 2001
From: YuviPanda <yuvipanda@gmail.com>
Date: Thu, 23 Jul 2026 10:19:44 -0700
Subject: [PATCH 3/3] Rename 'tips' to 'best practices'

---
 docs/source/{tips.md => best-practices.md} | 4 ++--
 docs/source/index.rst                      | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)
 rename docs/source/{tips.md => best-practices.md} (89%)

diff --git a/docs/source/tips.md b/docs/source/best-practices.md
similarity index 89%
rename from docs/source/tips.md
rename to docs/source/best-practices.md
index 0fcc58d56..4d53b78f6 100644
--- a/docs/source/tips.md
+++ b/docs/source/best-practices.md
@@ -1,6 +1,6 @@
-# Tips for using Traitlets
+# Best Practices
 
-A collection of useful design tips for using traitlets in your
+A collection of useful design tips & best practices for using traitlets in your
 application or library.
 
 ## Avoid using "pure config" objects
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 235c1cf86..88b7cfa42 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -23,7 +23,7 @@ the configuration machinery.
     trait_types
     defining_traits
     api
-    tips
+    best-practices
     config
     config-api
     utils