From c76e4eed80e214070895809233b82e1738c6bea2 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jan=20Kl=C3=B6tzke?= <jan@kloetzke.net>
Date: Fri, 7 Jul 2023 21:44:40 +0200
Subject: [PATCH] doc: update 0.23 release notes

---
 doc/manual/policies.rst |  2 ++
 doc/releases/0.23.rst   | 44 +++++++++++++++++++++++++++++++++++++++++
 2 files changed, 46 insertions(+)

diff --git a/doc/manual/policies.rst b/doc/manual/policies.rst
index 704927cef..44cee6429 100644
--- a/doc/manual/policies.rst
+++ b/doc/manual/policies.rst
@@ -564,6 +564,8 @@ New behavior
    Bob checks if the ``commit`` and / or ``tag`` is on the configured ``branch`` and
    performs a checkout of the ``commit`` on a local ``branch``.
 
+.. _policies-fixImportScmVariant:
+
 fixImportScmVariant
 ~~~~~~~~~~~~~~~~~~~
 
diff --git a/doc/releases/0.23.rst b/doc/releases/0.23.rst
index 4d1cd8dea..7f9de749b 100644
--- a/doc/releases/0.23.rst
+++ b/doc/releases/0.23.rst
@@ -35,6 +35,40 @@ New features
   operation Bob waits 3 seconds before retrying. By default no retries are
   made. See :ref:`configuration-recipes-scm`.
 
+Backwards incompatible changes
+------------------------------
+
+* Better support for ``checkoutScript`` changes with respect to recipes that
+  utilize :ref:`configuration-recipes-checkoutUpdateIf`. (:issue:`506`)
+
+  The tracking of recipe changes was not sufficient for build-only updates of
+  checkouts that involve the ``import``-SCM or recipes that utilize
+  :ref:`configuration-recipes-checkoutUpdateIf`. Bob was over-cautious and
+  prevented running these updates if *anything* related to the checkout step
+  changed.
+
+  To make the behaviour more predictable, Bob now tracks the related state more
+  closely. Updates of checkouts in build-only mode are now only prevented if an
+  ``import``-SCM is changed. So changes to the ``checkoutScript`` will always
+  trigger the update in build-only mode and run the affected parts of the
+  ``checkoutScript``.
+* Use Python to extract zip and tar files only on Windows.
+
+  The ``tarfile`` and ``zipfile`` Python modules are slower and have
+  behavioural differences compared to their native implementations. The
+  ``tarfile`` module in particular differs in the handling of file modes (it
+  does not behave like GNU tar with ``--no-same-permissions`` which is used by
+  Bob). The ``zipfile`` module looks safer but is certainly slower than the
+  native implementation. Consequently, the Python implementations are not used
+  on POSIX systems anymore, including MSYS2. This might break builds when these
+  essential tools are not installed.
+
+  On the other hand the ``unzip`` and ``tar`` tools are usually not available
+  on native Windows installations. There even seem to be broken ``unzip`` tools
+  out there in the wild (:issue:`496`). For this reason, Bob prefers to use
+  Python to extract tar and zip files on native Windows installations (*not*
+  MSYS2).
+
 Bug fixes
 ---------
 
@@ -59,3 +93,13 @@ Bug fixes
   package is unshared, the workspace link in the project tree should be
   removed. The bug was that Bob actually cleared the shared location instead of
   removing the symlink. (:issue:`522`)
+* Fixed broken variant handling regarding the ``dir`` attribute of ``import``
+  SCMs. Bob versions before 0.23 contained a bug where the ``dir`` attribute of
+  an ``import`` SCM was not included in the :term:`Variant-Id` calculation.
+  This can cause build failures or wrongly used binary artifacts if just the
+  ``dir`` attribute of an ``import`` SCM is changed. Because the fix cannot be
+  made in a backwards compatible way, a new :ref:`policies-fixImportScmVariant`
+  policy was introduced.
+* Fixed handling of nested annotated git tags in :ref:`manpage-bob-status`.
+  Even though nested tags, that is a tag that points at a tag, could be checked
+  out successfully, the workspace was flagged as "switched". (:issue:`520`)