From 98f82f8e75157cc1eda1e7a462021e4be0527398 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@crate.io>
Date: Tue, 5 Nov 2024 17:38:14 +0100
Subject: [PATCH] CHANGES: Update wording in section about version 1.0.0

---
 CHANGES.rst | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/CHANGES.rst b/CHANGES.rst
index bbfdd997..8d71af19 100644
--- a/CHANGES.rst
+++ b/CHANGES.rst
@@ -5,13 +5,13 @@ Changes for crate
 Unreleased
 ==========
 
-- The SQLAlchemy dialect has been split off into the `sqlalchemy-cratedb`_
-  package. See `Migrate from crate.client to sqlalchemy-cratedb`_ to learn
-  about necessary migration steps.
-- Returned Python ``datetime`` objects are now always timezone-aware,
-  using UTC by default. This is a possible BREAKING CHANGE: Removed the use
-  of "naive" Python ``datetime`` objects, i.e. instances without ``tzinfo``
-  attribute set.
+- BREAKING CHANGE: The SQLAlchemy dialect has been split off into
+  the `sqlalchemy-cratedb`_ package, see notice below.
+- Feature: Returned Python ``datetime`` objects are now always timezone-aware,
+  using UTC by default.
+  It may be a breaking change for some users of the library that don't expect
+  to receive "aware" instead of "naive" Python ``datetime`` objects from now
+  on, i.e. instances with or without the ``tzinfo`` attribute set.
   When no ``time_zone`` information is specified when creating a database
   connection or cursor, ``datetime`` objects will now use Coordinated
   Universal Time (UTC), like CrateDB is storing timestamp values in this
@@ -19,13 +19,11 @@ Unreleased
   This update is coming from a deprecation of Python's
   ``datetime.utcfromtimestamp()``, which is effectively also phasing out
   the use of "naive" timestamp objects in Python, in favor of using
-  timezone-aware objects, also to represent datetimes in UTC. It may be a
-  breaking change for some users of the library that don't expect to
-  receive "aware" ``datetime`` objects from now on.
-- Configured DB API interface attribute ``threadsafety = 1``, which signals
-  "Threads may share the module, but not connections."
-- Added ``error_trace`` to string representation of an Error to relay
-  server stacktraces into exception messages.
+  timezone-aware objects, also to represent datetimes in UTC.
+- Feature: Configured DB API interface attribute ``threadsafety = 1``,
+  which signals "Threads may share the module, but not connections."
+- Feature: Added ``error_trace`` to string representation of an Error,
+  to relay server stacktraces into exception messages.
 - Refactoring: The module namespace ``crate.client.test_util`` has been
   renamed to ``crate.testing.util``.
 - Error handling: At two spots in cursor / value converter handling, where
@@ -35,6 +33,13 @@ Unreleased
   namespaces" for the ``crate`` namespace package, see `PEP 420`_.
 
 
+.. note::
+
+    For learning about the transition to `sqlalchemy-cratedb`_,
+    we recommend to read the enumeration of necessary migration steps
+    at `Migrate from crate.client to sqlalchemy-cratedb`_.
+
+
 .. _Migrate from crate.client to sqlalchemy-cratedb: https://cratedb.com/docs/sqlalchemy-cratedb/migrate-from-crate-client.html
 .. _PEP 420: https://peps.python.org/pep-0420/
 .. _sqlalchemy-cratedb: https://pypi.org/project/sqlalchemy-cratedb/