From 46e93ccd123a70e4d66a52281ae8d9d0fb1b523f Mon Sep 17 00:00:00 2001
From: Silvan Melchior <silvan.melchior@zuehlke.com>
Date: Fri, 14 Jul 2023 17:53:16 +0200
Subject: [PATCH] migration guide

---
 README.md                       |  2 ++
 confz/base_config.py            |  2 +-
 docs/source/index.rst           |  1 +
 docs/source/migration_guide.rst | 35 +++++++++++++++++++++++++++++++++
 4 files changed, 39 insertions(+), 1 deletion(-)
 create mode 100644 docs/source/migration_guide.rst

diff --git a/README.md b/README.md
index 2d4daa2..4822bac 100644
--- a/README.md
+++ b/README.md
@@ -20,6 +20,8 @@ It furthermore supports you in common use cases like:
 * Config changes for unit tests
 * Custom config sources
 
+**UPDATE**: ConfZ 2 is here, with support for pydantic 2 and improved naming conventions.
+Check out the [migration guide](https://confz.readthedocs.io/en/latest/migration_guide.html). 
 
 ## :package: Installation
 
diff --git a/confz/base_config.py b/confz/base_config.py
index 8682051..21a2af5 100644
--- a/confz/base_config.py
+++ b/confz/base_config.py
@@ -53,7 +53,7 @@ def __call__(cls, config_sources: Optional[ConfigSources] = None, **kwargs):
 
 
 class BaseConfig(BaseModel, metaclass=BaseConfigMetaclass, frozen=True):
-    """Base class, parent of every config class. Internally wraps :class:`BaseModel`of
+    """Base class, parent of every config class. Internally wraps :class:`BaseModel` of
     pydantic and behaves transparent except for two cases:
 
     - If the constructor gets `config_sources` as kwarg, these sources are used as
diff --git a/docs/source/index.rst b/docs/source/index.rst
index fc6c3c8..e75a6ab 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -39,6 +39,7 @@ Contents
    :maxdepth: 2
 
    usage/usage
+   migration_guide
    reference/reference
 
 
diff --git a/docs/source/migration_guide.rst b/docs/source/migration_guide.rst
new file mode 100644
index 0000000..87e7816
--- /dev/null
+++ b/docs/source/migration_guide.rst
@@ -0,0 +1,35 @@
+Migration Guide
+===============
+
+This guide helps you to easily migrate to ConfZ 2, which supports pydantic 2 and
+improves naming conventions.
+
+New Class Names
+---------------
+
+We renamed many classes to better reflect their purpose instead of being tied to the
+package name. The following table summarizes all changes. Please make sure you adjust
+your imports accordingly.
+
+====================  ===============
+ConfZ v1              ConfZ v2
+====================  ===============
+ConfZ                 BaseConfig
+ConfZSource           ConfigSource
+ConfZSources          ConfigSources
+ConfZCLArgSource      CLArgSource
+ConfZDataSource       DataSource
+ConfZEnvSource        EnvSource
+ConfZFileSource       FileSource
+ConfZException        ConfigException
+ConfZUpdateException  UpdateException
+ConfZFileException    FileException
+====================  ===============
+
+Pydantic v2
+-----------
+
+Once initialized, a confz BaseConfig class behaves mostly like a regular pydantic
+BaseModel class. Pydantic 2 comes with quite some changes, which might affect your code,
+depending on the used functionalities. Check out the
+`migration guide <https://docs.pydantic.dev/latest/migration/>`_.