Merge #813: Release 0.9 RC2

CMakeLists.txt

@@ -5,8 +5,8 @@ endif()
 
 set(API_VERSION "0.9")
 project(Quotient VERSION "${API_VERSION}.0" LANGUAGES CXX)
-set(PRE_STAGE "rc")
-set(FULL_VERSION ${PROJECT_VERSION}~${PRE_STAGE})
+set(PRE_STAGE "rc2")
+string(JOIN ~ FULL_VERSION ${PROJECT_VERSION} ${PRE_STAGE})
 
 message(STATUS)
 message(STATUS "Configuring ${PROJECT_NAME} ${FULL_VERSION} ==>")

CODE_GENERATION.md

@@ -1,14 +1,11 @@
 # Generated C++ code for CS API
 
-The code in `Quotient/csapi`, `Quotient/identity` and
-`Quotient/application-service`, although stored in Git, is actually generated
-from the official Matrix Client-Server API definition files. If you're unhappy
-with something in there and want to improve that, you have to understand the way
-these files are produced and setup some additional tooling. The shortest
-possible procedure resembling the below text can be found in
-.github/workflows/ci.yml (regeneration of those files is tested in CI) - see
-the tasks "Get CS API definitions; clone and build GTAD" and
-"Regenerate API code".
+The code in `Quotient/csapi`, and `Quotient/application-service`, although stored in Git, is
+actually generated from the official Matrix Client-Server API definition files. If you're unhappy
+with something in there and want to improve that, you have to understand the way these files are
+produced and setup some additional tooling. The shortest possible implementation of the procedure
+described below can be found in .github/workflows/ci.yml (regeneration of those files is tested
+in CI) - see the tasks "Get CS API definitions; clone and build GTAD" and "Regenerate API code".
 
 ## Why generate the code at all?
 
@@ -30,25 +27,25 @@ that also briefly touches on GTAD - the tool written for the purpose.
 
    You can also just clone GTAD sources to keep them separate from libQuotient:
    `git clone --recursive https://github.com/quotient-im/gtad.git`
-2. Configure and build GTAD: same as libQuotient, it uses CMake so this should
-   be very straightforward (if not - you're probably not quite ready for this
-   stuff anyway).
-3. Get Matrix CS API definitions from a matrix-spec repo. Although the official
-   repo is at https://github.com/matrix-org/matrix-spec.git` (formerly
-   https://github.com/matrix-org/matrix-doc.git), you cannot use its main branch
-   with GTAD 0.9 (used for the current - 0.8 - version of libQuotient) because
-   the project has recently moved to OpenAPI 3 and GTAD does not support it yet.
-   For that reason as well as build predictability (the official Matrix repo
-   doesn't check whether a particular change breaks code generation), a soft
-   fork of the official definitions is kept at
-   https://github.com/quotient-im/matrix-spec.git - that guarantees buildability
-   of the generated code. This repo closely follows the official one (but maybe
-   not its freshest commit), applying a few adjustments on top. And of course
-   you can use your own repository if you need to change the API definition.
-4. If you plan to submit a PR with the generated code to libQuotient or just
-   would like it to be properly formatted, you should either ensure you have
-   clang-format (version 13 at least) in your PATH or pass
-   `-DCLANG_FORMAT=<path>` to CMake, as mentioned in the next section.
+
+2. Configure and build GTAD: same as libQuotient, it uses CMake so this should be very
+   straightforward (if not - you're probably not quite ready for this stuff anyway). It's only
+   tested on Linux but doesn't use anything Linux-specific; Windows, in particular, should be
+   just fine.
+
+3. Get Matrix CS API definitions from a matrix-spec repo. Although the official repo is at
+   https://github.com/matrix-org/matrix-spec.git`, it is not recommended to use its main branch
+   directly because the official Matrix repo doesn't check whether a particular change breaks code
+   generation or changes the generated API (it's a completely separate project after all). For that
+   reason, a soft fork of the official definitions is kept at
+   https://github.com/quotient-im/matrix-spec.git - that guarantees buildability of the generated
+   code and also has certain tweaks to make the generated API better. This repo closely follows
+   the official one (but maybe not its freshest commit). And of course you can fork it and use your
+   own repository if you need to change the API definition.
+
+4. If you plan to submit a PR with the generated code to libQuotient or just would like it to be
+   properly formatted, you should either ensure you have clang-format (version 16 at least) in your
+   PATH or pass `-DCLANG_FORMAT=<path>` to CMake, as mentioned in the next section.
 
 ## Generating CS API contents
 
@@ -60,11 +57,11 @@ that also briefly touches on GTAD - the tool written for the purpose.
    `-DCLANG_FORMAT=/path/to/clang-format` to the line above. If everything's
    right, the detected locations will be mentioned in CMake output and
    an additional build target called `update-api` will be configured.
-2. Generate the code: `cmake --build <your build dir> --target update-api`.
-   Building this target will create (overwriting without warning) source files
-   in `Quotient/csapi`, `Quotient/identity`, `Quotient/application-service` for
-   all YAML files it can find in `/path/to/matrix-spec/data/api/client-server`
-   and their dependencies.
+
+2. Generate the code: `cmake --build <your build dir> --target update-api`. Building this target
+   will create (overwriting without warning) source files in `Quotient/csapi`,
+   `Quotient/application-service` for all YAML files it can find in
+   `/path/to/matrix-spec/data/api/client-server` and their dependencies.
 
 ## Changing generated code
 
@@ -154,6 +151,7 @@ an existing one beyond minor adjustments):
 4. Once the MSC is accepted, you can officially submit your changes in API
    definitions as a "spec PR" to the official repo.
 
-In any case, when submitting a PR for libQuotient, please make sure generated
-files are committed separately from non-generated ones (no need to make two PRs;
-just separate the files in different commits).
+In any case, when submitting a PR for libQuotient, please make sure generated files are committed
+separately from non-generated ones (no need to make two PRs; just separate the files in different
+commits). This helps in situations when the same `gtad.yaml` or Mustache templates are
+cherry-picked between branches or back/forward-ported.

CONTRIBUTING.md

@@ -87,22 +87,22 @@ It's not practical to fix old contributions in git, so if one is forgotten,
 do not try to fix them.  We presume that if someone sometimes used a DCO,
 a commit without a DCO is an accident and the DCO still applies.
 -->
+
 ### License
 
 Unless a contributor explicitly specifies otherwise, we assume contributors
 to agree that all contributed code is released either under *LGPL v2.1 or later*.
 This is more than just [LGPL v2.1 libQuotient now uses](./COPYING)
-because the project plans to switch to LGPL v3 for library code in the near future.
+because the project plans to eventually switch to LGPL v3 for library code.
 <!-- The below is invalid yet!
 All new contributed material that is not executable, including all text when not executed, is also released under the
 [Creative Commons Attribution 4.0 International (CC BY 4.0) license](https://creativecommons.org/licenses/by/4.0/) or later.
 -->
 
-Any components proposed for reuse should have a license that permits releasing
-a derivative work under *LGPL v3 or later* (that includes licenses permitting
-*LGPL v2.1 or later* but not *LGPL v2.1 only*). In any case, the component
-should be redistributable under a license from
-[the list approved by OSI](https://opensource.org/licenses), no exceptions.
+Any components proposed for reuse should have a license that permits releasing a derivative work
+under *LGPL v3 or later* (that includes licenses permitting *LGPL v2.1 or later* but not
+*LGPL v2.1 only*). While this rule can be negotiated in some situations, using only licenses from
+[the list approved by OSI](https://opensource.org/licenses) is non-negotiable.
 
 We use [SPDX](https://spdx.dev) conventions for copyright statements. Please
 follow them when making a sizable contribution: add your name and year to
@@ -150,10 +150,12 @@ should follow it. Reasonable deviations from the defined style are allowed;
 use `// clang-format off` and `// clang-format on` to protect them.
 
 Most fundamental things from `.clang-format`:
-* We (mostly) use Webkit style: 4-space indents, no tabs, no trailing spaces, no last empty lines.
-  If you see code that doesn't follow this, fix it on the spot, thank you.
+* Our style is based on that of Webkit: 4-space indents, no tabs, no trailing spaces, no empty lines
+  at the end of the file. If you see code that doesn't follow this, fix it on the spot, thank you.
 * Prefer keeping lines within 100 characters. Slight overflows are ok if that
-  helps readability. Ideally, just use `clang-format` to format lines.
+  helps readability.
+
+Ideally, just use `clang-format` to format lines.
 
 ### API conventions
 
@@ -181,9 +183,9 @@ so tread carefully).
 
 ### Generated C++ code for CS API
 
-The code in `Quotient/csapi`, `Quotient/identity` and `Quotient/application-service`, although
-stored in Git, is actually generated from the official Matrix Client-Server API definition files.
-Make sure to read [CODE_GENERATION.md](./CODE_GENERATION.md) before trying to change anything there.
+The code in `Quotient/csapi` and `Quotient/application-service`, although stored in Git, is
+actually generated from the official Matrix Client-Server API definition files. Make sure to read
+[CODE_GENERATION.md](./CODE_GENERATION.md) before trying to change anything there.
 
 
 ## Documentation changes
@@ -253,7 +255,8 @@ Further sections are for those who's going to actively hack on the library code.
     questions at your pull request.
 * Prefer `std::unique_ptr<>` over `QScopedPointer<>`; `std::as_const()` to `qAsConst()`; 
   `std::swap()` to `qSwap()` etc.; basically, do not use compat facilities provided by Qt if the 
-  standard library provides an _equivalent_ facility.
+  standard library provides an _equivalent_ facility (Qt containers, `qHash` are not _equivalent_
+  to STL counterparts, e.g.).
 
 * When you write logs within the library always use logging categories defined in
   `logging_categories_p.h` instead of plain `qDebug()`, to avoid a log line being assigned

README.md

@@ -131,11 +131,11 @@ attribution) the source code of [Quaternion](https://github.com/quotient-im/Quat
 ### API/ABI stability
 
 Since Quotient 0.7.2, symbols in all header files of libQuotient *except files ending with `_p.h`
-and `namespace _impl`* are considered public and covered by API/ABI stability guarantees.
+and namespace `_impl`* are considered public and covered by API/ABI stability guarantees.
 Specifically, the API and ABI are backwards compatible within every minor version (0.7.x releases)
 with every next minor version (0.8, e.g.) breaking the compatibility. Once we reach 1.0, this rule
 will apply to the major version, aligning with [semantic versioning](https://semver.org/) rules.
-`_p.h` files and `namespace _impl` are not covered by these guarantees; client code should not
+`*_p.h` files and namespace `_impl` are not covered by these guarantees; client code should not
 directly include these files, nor use symbols defined in these locations.
 
 ## Building the library