docs: 2.3.0 release announcement updated

docs/blog/posts/2.3.0-released.md

@@ -1,6 +1,5 @@
 ---
-draft: true
-date: 2024-09-24
+date: 2024-09-27
 authors:
  - mpusz
 categories:
@@ -115,7 +114,7 @@ of the affine space abstractions and how they influence temperature handling.
 
 After a lengthy discussion on handling such scenarios, we decided to:
 
-- make the above code ill-formed (:boom: **breaking change** :boom:),
+- make the above code deprecated (:boom: **breaking change** :boom:),
 - provide an alternative way to create a `quantity` with the `delta` quantity construction helper.
 
 Here are the main points of this new design:
@@ -198,12 +197,12 @@ approach required additional types to be introduced for no good reason.
       static constexpr auto reference = si::second;
       static constexpr auto point_origin = default_point_origin(reference);
       using rep = decltype(Timestamp::seconds);
-  
+
       static constexpr convert_implicitly<rep> to_numerical_value(Timestamp ts)
       {
         return ts.seconds;
       }
-  
+
       static constexpr convert_explicitly<Timestamp> from_numerical_value(rep v)
       {
         return Timestamp(v);
@@ -219,19 +218,24 @@ approach required additional types to be introduced for no good reason.
       static constexpr auto reference = si::second;
       static constexpr auto point_origin = default_point_origin(reference);
       using rep = decltype(Timestamp::seconds);
-  
+
       static constexpr convert_implicitly<quantity<reference, rep>> to_quantity(Timestamp ts)
       {
         return ts.seconds * si::second;
       }
-  
+
       static constexpr convert_explicitly<Timestamp> from_quantity(quantity<reference, rep> q)
       {
         return Timestamp(q.numerical_value_ref_in(si::second));
       }
     };
     ```
 
+!!! note
+
+    The old behavior is deprecated and will be removed in future releases.
+
+
 ## `mag<pi>`
 
 With this release, we introduced a new strongly-typed constant to create a magnitude involving
@@ -252,6 +256,88 @@ is more consistent:
     inline constexpr struct degree final : named_unit<{u8"°", "deg"}, mag_pi / mag<180> * si::radian> {} degree;
     ```
 
+!!! note
+
+    The old `mag_pi` helper is marked as deprecated and will be removed in future releases.
+
+
+## Common units
+
+Adding or subtracting two quantities of different units will force the library to find a common
+unit for those. This is to prevent data truncation. For the cases when one of the units is an
+integral multiple of the another, the resulting quantity will use a "smaller" one in its result.
+For example:
+
+```cpp
+static_assert((1 * kg + 1 * g).unit == g);
+static_assert((1 * km + 1 * mm).unit == mm);
+static_assert((1 * yd + 1 * mi).unit == yd);
+```
+
+However, in many cases an arithmetic on quantities of different units will result in a yet another
+unit. This happens when none of the source units is an integral multiple of another. In such cases,
+the library returns a special type that denotes that we are dealing with a common unit of such
+an equation.
+
+Previously we returned a scaled unit calculated against our arbitrarily appointed reference unit.
+This resulted often in a long and messy type exposing the prime-factorized magnitude of the unit
+(implementation detail). In this release, we introduced a new `common_unit` wrapper for such cases:
+
+=== "Now"
+
+    ```cpp
+    quantity q = 1 * km + 1 * mi;  // quantity<common_unit<international::mile, si::kilo_<si::metre>>{}, int>
+    ```
+
+=== "Before"
+
+    ```cpp
+    quantity q = 1 * km + 1 * mi;  // quantity<scaled_unit<magnitude<power_v<2, 3>{}, power_v<5, -3>{}>{}, si::metre>{}, int>
+    ```
+
+!!! note
+
+    A user should never explicitly instantiate a `common_unit` class template. The library's
+    framework will do it based on the provided quantity equation.
+
+Such units need special printing rules for their symbols. As they represent a minimum set of common
+units resulting from the addition or subtraction of multiple quantities, from this release, we
+print all of them as a scaled version of the source unit. Previously we were printing them relative
+to some arbitrary reference unit (implementation detail) that often was not spelled by the user at
+all in the source code. For example the following:
+
+```cpp
+std::cout << 1 * km + 1 * mi << "\n";
+std::cout << 1 * nmi + 1 * mi << "\n";
+std::cout << 1 * km / h + 1 * m / s << "\n";
+```
+
+will print:
+
+=== "Now"
+
+    ```text
+    40771 ([1/25146] mi = [1/15625] km)
+    108167 ([1/50292] mi = [1/57875] nmi)
+    23 ([1/5] km/h = [1/18] m/s)
+    ```
+
+=== "Before"
+
+    ```text
+    40771 [8/125] m
+    108167 [4/125] m
+    23 [1/18] m/s
+    ```
+
+Thanks to the above, it might be easier for the user to reason about the magnitude of the resulting
+unit and its impact on the value stored in the quantity.
+
+!!! info
+
+    In order to provide `common_unit` strong type unit wrapper we had to rename all the
+    `common_XXX()` functions to `get_common_XXX()` (:boom: **breaking change** :boom:).
+
 
 ## Superpowers of the unit `one`
 
@@ -266,7 +352,7 @@ In this release, we also added a long-awaited change. From now on a quantity of
     ```cpp
     quantity<one> inc(quantity<one> q) { return q + 1; }
     void legacy(double) { /* ... */ }
-    
+
     if (auto q = inc(42); q != 0)
       legacy(static_cast<int>(q));
     ```
@@ -365,10 +451,16 @@ From now on, every named unit in the library can be prefixed with the SI or IEC
 ## `iec80000` system renamed to `iec`
 
 As we mentioned IEC already, in this release, we decided to rename the name of the system and its
-corresponding namespace from `iec80000` to `iec` (:boom: **breaking change** :boom:).
+corresponding namespace from `iec80000` to `iec` (:boom: **breaking change** :boom:). This involves
+renaming of a defining header file and of the namespace it provides.
+
+Wit this change it should be easier to type and is more correct for some quantities and units that
+are introduced by IEC but not necessarily in the ISO/IEC 80000 series of documents (e.g., `iec::var`).
+
+!!! note
 
-This should be easier to type and is more correct for some quantities and units that are introduced
-by IEC but not necessarily in the ISO/IEC 80000 series of documents (e.g., `iec::var`).
+    The old `iec80000` namespace in _iec8000.h_ is marked as deprecated and will be removed in
+    future releases.
 
 
 ## Error messages-related improvements