docs(faq): explain why Pydantic is not used

AnasHasan786 · Lee-W · commit c1884bddbeb6 · 2025-06-08T17:07:11.000+09:00
diff --git a/docs/faq.md b/docs/faq.md
@@ -82,6 +82,20 @@ git revert --no-commit <SHA>
 git commit -m "revert: foo bar"
 ```
 
+## Why don't we use Pydantic?
+
+While Pydantic is a powerful and popular library for data validation, we intentionally avoid using it in this project to keep our dependency tree minimal and maintainable.
+
+Including Pydantic would increase the chances of version conflicts for users - especially with major changes introduced in Pydantic v3. Because we pin dependencies tightly, adding Pydantic could unintentionally restrict what other tools or libraries users can install alongside `commitizen`.
+
+Moreover we don't rely on the full feature set of Pydantic. Simpler alternatives like Python's built-in `TypedDict` offer sufficient type safety for our use cases, without the runtime overhead or dependency burden.
+
+In short, avoiding Pydantic helps us:
+- Keep dependencies lightweight
+- Reduce compatibility issues for users
+- Maintain clarity about what contributors should and shouldn't use
+
+
 ## I got `Exception [WinError 995] The I/O operation ...` error
 
 This error was caused by a Python bug on Windows. It's been fixed by [this PR](https://github.com/python/cpython/pull/22017), and according to Python's changelog, [3.8.6rc1](https://docs.python.org/3.8/whatsnew/changelog.html#python-3-8-6-release-candidate-1) and [3.9.0rc2](https://docs.python.org/3.9/whatsnew/changelog.html#python-3-9-0-release-candidate-2) should be the accurate versions first contain this fix. In conclusion, upgrade your Python version might solve this issue.
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -107,6 +107,7 @@ packages = [{ include = "commitizen" }, { include = "commitizen/py.typed" }]
 [tool.poetry.group.dev.dependencies]
 ipython = "^8.0"
 tox = ">4"
+poethepoet = "^0.34.0"
 
 [tool.poetry.group.test.dependencies]
 pytest = ">=7.2,<9.0"
