diff --git a/CHANGELOG.md b/CHANGELOG.md
index 84ad77e..7d632bf 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,6 +1,16 @@
 # Changelog
 
-## v1.8.0 - 2023-04-18
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [Unreleased]
+
+### Changed
+
+- **BREAKING CHANGE** #236/240 - Upgrade to Pydantic v2. 
+
+## [1.8.0] - 2023-04-18
 
 ### Added
 
@@ -13,7 +23,7 @@
 - #77/#188 - `sync_from()` and `sync_to()` now return the `Diff` that was applied.
 - #211 - Loosened `packaging` and `structlog` library dependency constraints for broader compatibility.
 
-## v1.7.0 - 2022-11-03
+## [1.7.0] - 2022-11-03
 
 ### Changed
 
@@ -31,15 +41,15 @@
 
 ### Fixed
 
-- #149 Limit redundant CI concurrency
+- #149 - Limit redundant CI concurrency
 
-## v1.6.0 - 2022-07-09
+## [1.6.0] - 2022-07-09
 
 ### Changed
 
 - #120 - Dropped support for Python 3.6, new minimum is Python 3.7
 
-## v1.5.1 - 2022-06-30
+## [1.5.1] - 2022-06-30
 
 ### Added
 
@@ -54,13 +64,13 @@
 - #115 - Fixed ReadTheDocs rendering pipeline
 - #118 - Fixed a regression in `DiffSync.get(modelname, identifiers)` introduced in 1.5.0
 
-## v1.5.0 - 2022-06-07
+## [1.5.0] - 2022-06-07
 
 ### Added
 
 - #106 - Add a new, optional, backend store based in Redis
 
-## v1.4.3 - 2022-03-03
+## [1.4.3] - 2022-03-03
 
 ### Fixed
 
@@ -70,9 +80,9 @@
 
 ### Changed
 
-- #103 Update development dependencies
+- #103 - Update development dependencies
 
-## v1.4.2 - 2022-02-28
+## [1.4.2] - 2022-02-28
 
 **WARNING** - #90 inadvertently introduced a breaking API change in DiffSync 1.4.0 through 1.4.2 (#101); this change was reverted in #102 for DiffSync 1.4.3 and later. We recommend not using this release, and moving to 1.4.3 instead.
 
@@ -80,7 +90,7 @@
 
 - #100 - Added explicit dependency on `packaging`.
 
-## v1.4.1 - 2022-01-26
+## [1.4.1] - 2022-01-26
 
 **WARNING** - #90 inadvertently introduced a breaking API change in DiffSync 1.4.0 through 1.4.2 (#101); this change was reverted in #102 for DiffSync 1.4.3 and later. We recommend not using this release, and moving to 1.4.3 instead.
 
@@ -88,7 +98,7 @@
 
 - #95 - Removed optional dependencies on `sphinx`, `m2r2`, `sphinx-rtd-theme`, `toml`.
 
-## v1.4.0 - 2022-01-24
+## [1.4.0] - 2022-01-24
 
 **WARNING** - #90 inadvertently introduced a breaking API change in DiffSync 1.4.0 through 1.4.2 (#101); this change was reverted in #102 for DiffSync 1.4.3 and later. We recommend not using this release, and moving to 1.4.3 instead.
 
@@ -117,19 +127,19 @@
 - #51 - Update minimum Pydantic version due to security advisory GHSA-5jqp-qgf6-3pvh
 - #63 - Fix type in Readme
 
-## v1.3.0 - 2021-04-07
+## [1.3.0] - 2021-04-07
 
 ### Added
 
 - #48 - added optional `callback` argument to `diff_from`/`diff_to`/`sync_from`/`sync_to` for use with progress reporting.
 
-## v1.2.0 - 2020-12-08
+## [1.2.0] - 2020-12-08
 
 ### Added
 
 - #45 - minimum Python version lowered from 3.7 to 3.6, also now tested against Python 3.9.
 
-## v1.1.0 - 2020-12-01
+## [1.1.0] - 2020-12-01
 
 ### Added
 
@@ -147,6 +157,6 @@
 
 - #44 - On CRUD failure, do not generate an extraneous "success" log message in addition to the "failed" message
 
-## v1.0.0 - 2020-10-23
+## [1.0.0] - 2020-10-23
 
 Initial release
diff --git a/docs/source/getting_started/index.rst b/docs/source/getting_started/index.rst
index 2b0e096..9f461ee 100644
--- a/docs/source/getting_started/index.rst
+++ b/docs/source/getting_started/index.rst
@@ -1,5 +1,5 @@
-###############
-Getting Started
-###############
+#########
+Upgrading
+#########
 
 .. mdinclude:: 01-getting-started.md
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 3b1a744..2c851f5 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -9,6 +9,7 @@ Welcome to DiffSync's documentation!
    getting_started/index
    core_engine/index
    examples/index
+   upgrading/index
    api/diffsync
    license/index
 
diff --git a/docs/source/upgrading/01-upgrading-to-2.0.md b/docs/source/upgrading/01-upgrading-to-2.0.md
new file mode 100644
index 0000000..10a7b08
--- /dev/null
+++ b/docs/source/upgrading/01-upgrading-to-2.0.md
@@ -0,0 +1,31 @@
+# Upgrading to 2.0
+
+With diffsync 2.0, there a couple of breaking changes. What they are and how to deal with them is described in this document.
+
+## Upgrade to Pydantic's major version 2
+
+A [migration guide](https://docs.pydantic.dev/latest/migration/) is available in the Pydantic documentation. Here are the key things that may apply to your usage of diffsync:
+
+- Any fields that are of type `Optional` now need to provide an explicit `None` default (you can use [bump-pydantic](https://github.com/pydantic/bump-pydantic) to deal with this automatically for the most part)
+
+```python
+from typing import Optional
+
+from diffsync import DiffSyncModel
+
+# Before
+class Person(DiffSyncModel):
+    _identifiers = ("name",)
+    _attributes = ("age",)
+
+    name: str
+    age: Optional[int]
+
+# After
+class BetterPerson(DiffSyncModel)
+    _identifiers = ("name",)
+    _attributes = ("age",)
+
+    name: str
+    age: Optional[int] = None
+```
\ No newline at end of file
diff --git a/docs/source/upgrading/index.rst b/docs/source/upgrading/index.rst
new file mode 100644
index 0000000..2c84dda
--- /dev/null
+++ b/docs/source/upgrading/index.rst
@@ -0,0 +1,5 @@
+########
+Ugrading
+########
+
+.. mdinclude:: 01-upgrading-to-2.0.md