From 5bbdddbc514a232b73b3602e178ea085363a3f7c Mon Sep 17 00:00:00 2001 From: Leo Kirchner Date: Fri, 18 Aug 2023 13:49:45 -0400 Subject: [PATCH] Bootstrap 2.0 migration docs for pydantic 2.0 change --- CHANGELOG.md | 40 ++++++++++++-------- docs/source/getting_started/index.rst | 6 +-- docs/source/index.rst | 1 + docs/source/upgrading/01-upgrading-to-2.0.md | 31 +++++++++++++++ docs/source/upgrading/index.rst | 5 +++ 5 files changed, 65 insertions(+), 18 deletions(-) create mode 100644 docs/source/upgrading/01-upgrading-to-2.0.md create mode 100644 docs/source/upgrading/index.rst 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