update release notes

docs/source/release_notes/release_notes_1.23.rst

@@ -33,7 +33,7 @@ content in target tag. Now we are failing on any error.
 | PR: https://pagure.io/koji/pull-request/2461
 | PR: https://pagure.io/koji/pull-request/2471
 
-In the last version we've introduced unified ``download_file`` method which also
+In the previous version we introduced unified ``download_file`` method which also
 checks downloaded content. There are minor updates improving this function
 especially in reaction to errors.
 
@@ -56,12 +56,12 @@ relevant logs.
 
 Fix of the bug which missed plugins in /usr/lib64 prefix.
 
-**clone-tag --config clones also extra info**
+**clone-tag --config also clones extra info**
 
 | PR: https://pagure.io/koji/pull-request/2472
 
 Formerly cloning skipped extra values. Nevertheless, extra values are becoming
-important part of config, so from now we are cloning also those.
+an important part of config, so from now we are cloning them.
 
 Library Changes
 ---------------
@@ -88,13 +88,21 @@ Case of signature hashes is properly ignored.
 It is probably mostly used by kojira, but it can be of some interest to
 automation scripts.
 
+Because of this, kojira will now correctly regenerate repos when tag extra
+values change.
+
 **getAverageBuildDuration sliding window**
 
 | PR: https://pagure.io/koji/pull-request/2421
 
-``getAverageBuildDuration`` returned average for all package builds. Old data
-could be irrelevant to new version of packages, so age in months can now be
-specified to limit data from which average is computed.
+The ``getAverageBuildDuration`` hub call returned an average for all builds for
+the given package.
+However, old data could be irrelevant to new versions of packages.
+Now the call offers an ``age`` option to limit the query (specified as number
+of months).
+
+The koji builder daemon now uses this option with a value of 6 months when
+adjusting the weight of ``buildArch`` tasks.
 
 **getBuildConfig returns inheritance history**
 
@@ -107,17 +115,17 @@ This behaviour is meant to be used with next change.
 
 | PR: https://pagure.io/koji/pull-request/2495
 
-Inherited tag extra fields could have been overriden but not removed. Now it can
-be done via CLIs ``edit-tag`` or ``editTag2`` respectively which has new
+Inherited tag extra fields could have been overridden but not removed. Now it can
+be done via CLIs ``edit-tag`` or ``editTag2`` respectively which has a new
 ``block_extra`` option.
 
 **deprecate getGlobalInheritance**
 
 | PR: https://pagure.io/koji/pull-request/2407
 
-It should be replaced by ``readFullInheritance`` which is more general and
-properly reflects various inheritance options. Call will be completely removed
-in koji 1.25.
+This call was never used in Koji.
+Clients should instead use the ``readFullInheritance`` call.
+The ``getGlobalInheritance`` call will be completely removed in Koji 1.25.
 
 **remove deprecated list-tag-history / tagHistory**
 
@@ -139,10 +147,17 @@ Builder Changes
 
 | PR: https://pagure.io/koji/pull-request/2485
 
-Buildroots were cleaned from builder after hard-coded amount of time. Basic
-cleanup was done after two minutes and completely removed after a day. Now both
-options are configurable as ``buildroot_basic_cleanup_delay`` and
-``buildroot_final_cleanup_delay``.
+Previously these times were hard coded.
+The ``buildroot_basic_cleanup_delay`` setting controls how long the builder will
+wait before basic cleanup of the buildroot (removing most content but leaving
+the directory). The default value is two minutes.
+The ``buildroot_final_cleanup_delay`` setting controls how long the build will
+wait before final cleanup of the buildroot (removing the rest).
+The default value is one day.
+Both values are specified in seconds.
+
+For historical context on why there are two separate delays, see
+`this bug <https://bugzilla.redhat.com/show_bug.cgi?id=192153>`.
 
 **livemedia-creator: pass --nomacboot on non-x86_64**
 
@@ -166,8 +181,9 @@ Bug which prevented proper usage of ``bootloader --append`` in kickstarts.
 
 | PR: https://pagure.io/koji/pull-request/2417
 
-If tag was deleted during ``waitrepo`` task, it waited until long timeout. Now
-it can fail immediately.
+Previously, if a tag was deleted while a ``waitrepo`` task was watching it, the
+task would not notice and wait until the timeout expired.
+Now it will fail when it detects that the tag has been deleted.
 
 System Changes
 --------------
@@ -176,19 +192,23 @@ System Changes
 
 | PR: https://pagure.io/koji/pull-request/2490
 
-One of the most important changes is dropping support for older python. We still
-support python 2.7 for builder (other components are python 3 only). It
-effectively means ending support for RHEL/CentOS 6 builders. In the same moment
-we are dropping yum support (it was used only with dist-repos) as RHEL7 and
+
+One of the most significant changes in this release is dropping support for
+older python versions.
+Koji no longer supports python 2.6, and only supports python 2.7 for the
+builder and cli.
+
+This effectively means ending support for RHEL/CentOS 6 builders.
+We are dropping yum support (it was used only with dist-repos) as RHEL7 and
 newer have full dnf stack.
 
 **report versions of components**
 
 | PR: https://pagure.io/koji/pull-request/2438
 
-There is a new API call ``getVersion`` (don't confuse with ``getAPIVersion``)
-which returns version of hub being connected to. Similarly, basic library
-provides ``koji.__version__`` field.
+There is a new hub API call named ``getVersion`` (don't confuse with
+``getAPIVersion``) which returns the version of Koji that the hub is running.
+Similarly, the ``koji`` library provides its version in ``koji.__version__``.
 
 Plugins
 -------
@@ -197,9 +217,10 @@ Plugins
 
 | PR: https://pagure.io/koji/pull-request/2441
 
-As qpid (or other amqps broker) can be unreachable for longer periods of time
-we've implemented local db queue, so no messages are lost. This behaviour needs
-to be turned on - check the documentation.
+As qpid (or other amqps broker) can be unreachable for long periods of time
+we've implemented a fallback queue in the database to avoid lost messages.
+This behaviour needs to be enabled - see
+:ref:`the documentation <protonmsg-config>`.
 
 Utilities Changes
 -----------------