diff options
| -rw-r--r-- | CONTRIBUTING.md | 55 | ||||
| -rw-r--r-- | README.md | 17 |
2 files changed, 47 insertions, 25 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7b534c32..56bc9d91 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -86,17 +86,18 @@ a commit without a DCO is an accident and the DCO still applies. --> ### License -Unless a contributor explicitly specifies otherwise, we assume that all -contributed code is released under [the same license as libQMatrixClient itself](./COPYING), -which is LGPL v2.1 as of the time of this writing. +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 libQMatrixClient now uses](./COPYING) +because the project plans to switch to LGPL v3 for library code in the near future. <!-- 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 v2.1. Moreover, the license of a proposed component -should be approved by OSI, no exceptions. +a derivative work under *LGPL v2.1 or later* or LGPL v3. Moreover, the license of +a proposed component should be approved by OSI, no exceptions. ## Vulnerability reporting (security issues) @@ -110,7 +111,7 @@ In any of these two options, _indicate that you have such information_ By default, we will give credit to anyone who reports a vulnerability in a responsible way so that we can fix it before public disclosure. If you want -to remain anonymous or pseudonymous instead, please let us know that; we will +to remain anonymous or pseudonymous instead, please let us know; we will gladly respect your wishes. If you provide a fix as a PR, you have no way to remain anonymous (and you also disclose the vulnerability thereby) so this is not the right way, unless the vulnerability is already made public. @@ -156,12 +157,12 @@ The code should strive to be DRY (don't repeat yourself), clear, and obviously c ### Generated C++ code for CS API The code in lib/csapi, lib/identity and lib/application-service, although -it resides in Git, is actually generated from the official Matrix -Swagger/OpenAPI definition files. If you're unhappy with something in these -directories and want to improve the code, 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 .travis.yml (our Travis CI -configuration actually regenerates those files upon every build). +it resides in Git, is actually generated from (a soft fork of) the official +Matrix Swagger/OpenAPI definition files. If you're unhappy with something in +these directories and want to improve the code, 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 .travis.yml +(our Travis CI configuration actually regenerates those files upon every build). The generating sequence only works with CMake atm; patches to enable it with qmake are (you guessed it) very welcome. @@ -209,16 +210,23 @@ Instead of relying on the event structure definition in the OpenAPI files, `gtad ### Library API and doc-comments -Whenever you add a new call to the library API that you expect to be used from client code, you must supply a proper doc-comment along with the call. Doxygen (with backslashes) style is preferred. You can find that some parts of the code still use JavaDoc (with @'s) style; feel free to replace it with Doxygen backslashes and if that bothers you. Some parts are not even documented; adding doc-comments to them is highly encouraged. +Whenever you add a new call to the library API that you expect to be used from client code, you must supply a proper doc-comment along with the call. Doxygen (with backslashes) style is preferred. You can find that some parts of the code still use JavaDoc (with @'s) style; feel free to replace it with Doxygen backslashes if that bothers you. Some parts are not even documented; adding doc-comments to them is highly encouraged. -Calls, data structures and other symbols not intended for use by clients should _not_ be exposed in (public) .h files, unless they are necessary to declare other public symbols. In particular, this involves private members (functions, typedefs, or variables) in public classes; use pimpl idiom to hide implementation details as much as possible. +Calls, data structures and other symbols not intended for use by clients +should _not_ be exposed in (public) .h files, unless they are necessary +to declare other public symbols. In particular, this involves private members +(functions, typedefs, or variables) in public classes; use pimpl idiom to hide +implementation details as much as possible. `_impl` namespace is reserved for +definitions that should not be used by clients and are not covered by +API guarantees. Note: As of now, all header files of libQMatrixClient are considered public; this may change eventually. ### Qt-flavoured C++ -This is our primary language. We don't have a particular code style _as of yet_ -but some rules-of-thumb are below: +This is our primary language. A particular code style is not enforced _yet_ but +[the PR imposing the common code style](https://github.com/QMatrixClient/libqmatrixclient/pull/295) +is planned to arrive in version 0.6. * 4-space indents, no tabs, no trailing spaces, no last empty lines. If you spot the code abusing these - we'll thank you for fixing it. * Prefer keeping lines within 80 characters. @@ -260,9 +268,12 @@ but some rules-of-thumb are below: ### Automated tests -There's no testing framework as of now; either Catch or Qt Test or both will be used eventually. However, as a stopgap measure, qmc-example is used for automated end-to-end testing. +There's no testing framework as of now; either Catch or Qt Test or both will +be used eventually. -Any significant addition to the library API should be accompanied by a respective test in qmc-example. To add a test you should: +As a stopgap measure, qmc-example is used for automated functional testing. +Therefore, any significant addition to the library API should be accompanied +by a respective test in qmc-example. To add a test you should: - Add a new private slot to the `QMCTest` class. - Add to the beginning of the slot the line `running.push_back("Test name");`. - Add test logic to the slot, using `QMC_CHECK` macro to assert the test outcome. ALL (even failing) branches should conclude with a QMC_CHECK invocation, unless you intend to have a "DID NOT FINISH" message in the logs under certain conditions. @@ -310,7 +321,7 @@ In Qt Creator, the following line can be used with the Clang code model ### Continuous Integration -We use Travis CI to check buildability and smoke-testing on Linux (GCC, Clang) and MacOS (Clang), and AppVeyor CI to build on Windows (MSVC). Every PR will go through these, and you'll see the traffic lights from them on the PR page. Failure on any platform will most likely entail a request to you for a fix before merging a PR. +We use Travis CI to check buildability and smoke-testing on Linux (GCC, Clang) and MacOS (Clang), and AppVeyor CI to build on Windows (MSVC). Every PR will go through these, and you'll see the traffic lights from them on the PR page. If your PR fails on any platform double-check that it's not your code causing it - and fix it if it is. ### Other tools @@ -323,7 +334,7 @@ Qt Creator, in addition, knows about clazy, an even deeper Qt-aware static analysis tool. Even level 1 clazy eats away CPU but produces some very relevant and unobvious notices, such as possible unintended copying of a Qt container, or unguarded null pointers. You can use this time to time (see Analyze menu in -Qt Creator) instead of loading your machine with deep runtime analysis. +Qt Creator) instead of hogging your machine with deep analysis as you type. ## Git commit messages @@ -343,7 +354,7 @@ When writing git commit messages, try to follow the guidelines in C++ is unfortunately not very coherent about SDK/package management, and we try to keep building the library as easy as possible. Because of that we are very conservative about adding dependencies to libQMatrixClient. That relates to additional Qt components and even more to other libraries. Fortunately, even the Qt components now in use (Qt Core and Network) are very feature-rich and provide plenty of ready-made stuff. -Regardless of the above paragraph (and as mentioned earlier in the text), we're now looking at possible options for automated testing, so PRs onboarding a test framework will be considered with much gratitude. +Regardless of the above paragraph (and as mentioned earlier in the text), we're now looking at possible options for futures and automated testing, so PRs onboarding those will be considered with much gratitude. Some cases need additional explanation: * Before rolling out your own super-optimised container or algorithm written @@ -367,4 +378,4 @@ Some cases need additional explanation: ## Attribution -This text is largely based on CONTRIBUTING.md from CII Best Practices Badge project, which is a collective work of its contributors (many thanks!). The text itself is licensed under CC-BY-4.0. +This text is based on CONTRIBUTING.md from CII Best Practices Badge project, which is a collective work of its contributors (many thanks!). The text itself is licensed under CC-BY-4.0. @@ -17,9 +17,19 @@ You can find authors of libQMatrixClient in the Matrix room: [#qmatrixclient:mat You can also file issues at [the project's issue tracker](https://github.com/QMatrixClient/libqmatrixclient/issues). If you have what looks like a security issue, please see respective instructions in CONTRIBUTING.md. ## Building and usage -So far the library is typically used as a git submodule of another project (such as Quaternion); however it can be built separately (either as a static or as a dynamic library). As of version 0.2, the library can be installed and CMake package config files are provided; projects can use `find_package(QMatrixClient)` to setup their code with the installed library files. PRs to enable the same for qmake are most welcome. - -The source code is hosted at GitHub: https://github.com/QMatrixClient/libqmatrixclient - checking out a certain commit or tag from GitHub (rather than downloading the archive) is the recommended way for one-off building. If you want to hack on the library as a part of another project (e.g. you are working on Quaternion but need to do some changes to the library code), you're advised to make a recursive check out of that project (in this case, Quaternion) and update the library submodule to its master branch. +So far the library is typically used as a git submodule of another project +(such as Quaternion); however it can be built separately (either as a static or +as a dynamic library). After installing the library the CMake package becomes +available for `find_package(QMatrixClient)` to setup the client code with +the installed library files. PRs to enable the same for qmake are most welcome. + +[The source code is hosted at GitHub](https://github.com/QMatrixClient/libqmatrixclient) - +checking out a certain commit or tag (rather than downloading the archive) is +the recommended way for one-off building. If you want to hack on the library +as a part of another project (e.g. you are working on Quaternion but need +to do some changes to the library code), you're advised to make a recursive +check out of that project (in this case, Quaternion) and update +the library submodule to its master branch. Tags consisting of digits and periods represent released versions; tags ending with `-betaN` or `-rcN` mark pre-releases. If/when packaging pre-releases, it is advised to replace a dash with a tilde. @@ -28,6 +38,7 @@ Tags consisting of digits and periods represent released versions; tags ending w - For Ubuntu flavours - zesty or later (or a derivative) is good enough out of the box; older ones will need PPAs at least for a newer Qt; in particular, if you have xenial you're advised to add Kubuntu Backports PPA for it - a Git client to check out this repo - Qt 5 (either Open Source or Commercial), version 5.6 or higher + (5.9 or higher is strongly recommended) - a build configuration tool: - CMake (from your package management system or [the official website](https://cmake.org/download/)) - or qmake (comes with Qt) |