From 360bedb12baf298d9fee03ec51f0398b6984ff30 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Mon, 11 Dec 2023 20:38:20 +0100 Subject: [PATCH 1/4] docs: project blog added --- docs/blog/.authors.yml | 6 ++ docs/blog/index.md | 1 + docs/blog/posts/2.0.0-released.md | 130 ++++++++++++++++++++++++++++++ mkdocs.yml | 10 +++ requirements.txt | 1 + 5 files changed, 148 insertions(+) create mode 100644 docs/blog/.authors.yml create mode 100644 docs/blog/index.md create mode 100644 docs/blog/posts/2.0.0-released.md diff --git a/docs/blog/.authors.yml b/docs/blog/.authors.yml new file mode 100644 index 0000000000..d8dbd8caaf --- /dev/null +++ b/docs/blog/.authors.yml @@ -0,0 +1,6 @@ +authors: + mpusz: + name: Mateusz Pusz + description: Creator + avatar: https://avatars.githubusercontent.com/u/506260 + url: https://github.com/mpusz diff --git a/docs/blog/index.md b/docs/blog/index.md new file mode 100644 index 0000000000..05761ac57f --- /dev/null +++ b/docs/blog/index.md @@ -0,0 +1 @@ +# Blog diff --git a/docs/blog/posts/2.0.0-released.md b/docs/blog/posts/2.0.0-released.md new file mode 100644 index 0000000000..4176482bb3 --- /dev/null +++ b/docs/blog/posts/2.0.0-released.md @@ -0,0 +1,130 @@ +--- +date: 2023-09-24 +authors: + - mpusz +categories: + - Releases +--- + +# What's new in mp-units 2.0? + +**After a year of hard work, we've just released mp-units 2.0.0. It can be obtained from +[GitHub](https://github.com/mpusz/mp-units/releases/tag/v2.0.0) and +[Conan](https://conan.io/center/recipes/mp-units?version=2.0.0).** + +In this post, we will describe all the changes introduced by the new version. + + + +## Why 2.0 if 1.0 was never released? + +Version 2 of the **mp-units** project is a huge change and a new quality for the users. +We did not want to pretend that 2.0 is an evolutionary upgrade of the previous version of the +project. It feels like a different product. + +We could start a new repo named "mp-units-v2" similarly to [range-v3](https://github.com/ericniebler/range-v3) +but we decided not to go this path. We kept the same repo and made the scope of the changes and +potential breakage explicit with a drastic bump in the project version. + +## What has changed? + +The answer is "nearly everything". The whole library and its documentation were rewritten nearly +from scratch. + +Here are the significant changes that the users can observe: + +- **Repository name** + + If you didn't notice, the repository name was changed from "mpusz/units" to "mpusz/mp-units". + +- **Header files content and layout** + + Previously, all the header files resided in the _include/units_ directory, and now they can be + found in _include/mp-units_. The project file tree was significantly changed as well. Many + files were moved to different subdirectories or renamed. + +- **Namespace** + + Previously, all the definitions were provided in the `units` namespace, and now they are in the + `mp_units` one. + +- **Abstractions, interfaces, definitions** + + The interfaces of all of the types were refactored, and we have a new way to construct a `quantity` + and `quantity_point`, we got unit symbols, and nearly all of the template arguments are now passed + by values thanks to class NTTP extensions in C++20. Also, systems definitions are much terser now + thanks to a new design approach. + +*[NTTP]: Non-Type Template Parameter + +- **Conan 2.0** + + Also, now we support Conan 2.0, which provides an updated way of handling dependencies. + +## What is gone? + +Some cornerstones of the initial design did not prove in practice and were removed while +we moved to version 2. + +### The downcasting facility + +The first and the most important of such features was removing the downcasting facility. +This feature is still a powerful metaprogramming technique that allows users to map long class template +instantiations to nicely named, short, and easy-to-understand user's strong types. + +Such mapping works perfectly fine for 1-to-1 relationships. However, we often deal with N-to-1 connections in the quantities and units domain. Here are only a few such examples: + +- _work_ and _torque_ have the same dimension $L^2MT^{-2}$, +- becquerel and hertz have the same definition of $s^{-1}$, +- litre and cubic decimetre have the same factor. + +In the above examples, multiple entities "wanted" to register different names for identical class +template instantiations, resulting in compile-time errors. We had to invent some hacks and +workarounds to make it work, but we were never satisfied with the outcome. + +Additionally, this facility could easily lead to ODR violations or provide different results +depending on which header files were included in the translation units. This was too vulnerable +to be considered a good practice here. + +*[ODR]: One Definition Rule + +### No UDLs anymore + +Over the years, we have learned that UDLs are not a good solution either. More information on this +subject can be found in the +[Why don't we use UDLs to create quantities?](../../getting_started/faq.md#why-dont-we-use-udls-to-create-quantities) +chapter. + +*[UDL]: User-Defined Literals + + +## New look and feel + +Here is a concise example showing you the new look and feel of the library: + +```cpp +#include +#include +#include +#include + +using namespace mp_units; +using namespace mp_units::si::unit_symbols; + +quantity avg_speed(quantity d, + quantity t) +{ return d / t; } + +int main() +{ + auto speed = avg_speed(220 * km, 2 * h); + std::println("{}", speed); // 30.5556 m/s +} +``` + +All of the changes we provided, although breaking ones, resulted in much better, +easier, and safer abstractions. These offer a new quantity on the market and hopefully will be +appreciated by our users. + +Please check our new documentation to learn about the latest version of the project and find out +how to benefit from all the new cool stuff we have here. diff --git a/mkdocs.yml b/mkdocs.yml index c4270a59f5..d7830db5f0 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -51,6 +51,14 @@ theme: # Plugins plugins: + - blog + - rss: + match_path: blog/posts/.* + date_from_meta: + as_creation: date + categories: + - categories + - tags - search - tags: tags_file: users_guide/examples/tags_index.md @@ -108,6 +116,8 @@ nav: - Quick Start: getting_started/quick_start.md - Installation and Usage: getting_started/installation_and_usage.md - FAQ: getting_started/faq.md + - Blog: + - blog/index.md - User's Guide: - Terms and Definitions: users_guide/terms_and_definitions.md - Framework Basics: diff --git a/requirements.txt b/requirements.txt index 8542ef45cb..3c371fe827 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,5 @@ conan pre-commit identify mkdocs-material +mkdocs-rss-plugin mike From 0f649c9f746c3a513fad242ec354b7602c43377b Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Mon, 11 Dec 2023 20:46:20 +0100 Subject: [PATCH 2/4] ci: mkdocs-rss-plugin dependency installation added --- .github/workflows/documentation.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index ef6890894c..52b628ba9e 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -46,7 +46,7 @@ jobs: mkdocs-material- - name: Installing pip packages run: | - pip install conan mkdocs-material mike + pip install conan mkdocs-material mkdocs-rss-plugin mike - name: Prepare git run: | git config --global user.name github-actions From b010d08f280bcff2a5a8621c018d2aa5be27e165 Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Mon, 11 Dec 2023 20:52:23 +0100 Subject: [PATCH 3/4] ci: `fetch-depth: 0` added to the documentation CI --- .github/workflows/documentation.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/documentation.yml b/.github/workflows/documentation.yml index 52b628ba9e..bd2fd56bb5 100644 --- a/.github/workflows/documentation.yml +++ b/.github/workflows/documentation.yml @@ -34,6 +34,8 @@ jobs: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 + with: + fetch-depth: 0 - uses: actions/setup-python@v4 with: python-version: 3.x From f1c35916934e91dde0aedb58fdb029c12c003f1b Mon Sep 17 00:00:00 2001 From: Mateusz Pusz Date: Mon, 11 Dec 2023 21:26:58 +0100 Subject: [PATCH 4/4] docs: Kona report added --- docs/blog/posts/kona-2023-report.md | 50 +++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) create mode 100644 docs/blog/posts/kona-2023-report.md diff --git a/docs/blog/posts/kona-2023-report.md b/docs/blog/posts/kona-2023-report.md new file mode 100644 index 0000000000..adfbec5e9e --- /dev/null +++ b/docs/blog/posts/kona-2023-report.md @@ -0,0 +1,50 @@ +--- +date: 2023-11-12 +authors: + - mpusz +categories: + - WG21 +--- + +# Report from the Kona 2023 ISO C++ Committee meeting + +**Several groups in the ISO C++ Committee reviewed the [P1935: A C++ Approach to Physical Units](https://wg21.link/p1935) +proposal in Belfast 2019 and Prague 2020. All those groups expressed interest in the potential +standardization of such a library and encouraged further work. The authors also got valuable +initial feedback that highly influenced the design of the V2 version of the mp-units library.** + +In the following years, we scoped on getting more feedback from the production and design and +developed version 2 of the **mp-units** library that resolves many issues raised by the users and +Committee members. The features and interfaces of this version are close to being the best we can +get with the current version of the C++ language standard. + + + +For the last ISO C++ Committee meeting, we provided three new proposals related to the +standardization of the quantities and units library: + +- [P2980: A motivation, scope, and plan for a physical quantities and units library](https://wg21.link/p2980R1), +- [P2981: Improving our safety with a physical quantities and units library](https://wg21.link/p2981R1), +- [P2982: `std::quantity` as a numeric type](https://wg21.link/p2982R1). + +Those were reviewed and briefly discussed in several groups: Numerics (SG6), Safety & Security +(SG23), and Library Evolution Working Group (LEWG). Most of the feedback was positive, and +the Committee is interested in spending more time on such proposals. + +!!! question "LEWG POLL: Given that our time is limited, more time should be promised for a quantities and units library" + + | SF | F | N | A | SA | + |----|----|---|---|----| + | 10 | 13 | 4 | 0 | 0 | + + Attendance: 22 + 6 + + Number of Authors: 4 + + Authors’ position: 4x SF + + Outcome: Strong consensus in favor + +Additionally, some concerns were raised about the large scope of the proposal. We were encouraged +to come back with more details and design rationale in a unified paper. This is what we are working +on now for the next Committee meeting that will happen in mid-March 2024 in Tokyo.