Improve documentation and contributor experience

CONTRIBUTING.md

@@ -0,0 +1,88 @@
+<!--
+SPDX-FileCopyrightText: 2023 Melvin Keskin <[email protected]>
+
+SPDX-License-Identifier: CC0-1.0
+-->
+
+# Contributing
+
+This is a guideline for contributing to QXmpp.
+
+## Git Hooks Setup
+
+QXmpp currently just provides a hook for code formatting before commiting.
+You can enable it as follows:
+```
+cd qxmpp
+./utils/setup-hooks.sh
+```
+This requires `git-clang-format` to be installed, though.
+
+## Pull-requests (PRs)
+
+You can submit suggestions for changes via GitHub pull-requests.
+The maintainers of QXmpp will review your code. However, everybody is welcome to review the code and give feedback.
+You can find the current maintainers and other people involved in the project in the `AUTHORS` file.
+
+### Guidelines for Creating PRs
+
+1. Do not use the *master* branch of your personal fork to create PRs. It leads to confusion and
+   makes it harder to check out your branch, making changes to it and in the end also merging your
+   PR into the *master* branch of the main repository.
+1. For fixes, target the branch of the latest release (e.g. *1.3*) instead of the *master* branch.
+1. Write short commit messages starting with an upper case letter and the imperative.
+1. Split your commits logically.
+1. Do not mix unrelated changes in the same PR.
+1. Check the tasks in the pull-request template when they are done or no changes were needed.
+
+## Testing
+
+After building QXmpp with `-DBUILD_TESTS=ON`, you can run QXmpp's unit tests in the build directory with:
+```
+make test
+```
+
+### Internal Tests
+
+There are some additional internal tests that only work with debug builds because they are using unexported symbols from the QXmpp library.
+You can enable those using `-DBUILD_INTERNAL_TESTS=ON`.
+They are also run using `make test`, along with the regular tests.
+
+### Integration Tests
+
+There are some tests that also provide integration testing with a real XMPP server.
+The code of those test cases is always built, but the cases are skipped when running `make test` without further configuration.
+
+You can enable them by exporting the following environment variables:
+
+* `QXMPP_TESTS_INTEGRATION_ENABLED=1`
+* `QXMPP_TESTS_JID=<jid>`
+* `QXMPP_TESTS_PASSWORD=<password>`
+
+Replace `<jid>` and `<password>` with the credentials of the account for connecting to the server.
+
+## Documentation
+
+The documentation is generated using Doxygen.
+You can enable it using the CMake option `-DBUILD_DOCUMENTATION=ON` and build it manually using:
+```
+make doc
+```
+
+The generated files are located in `doc/html/`.
+You can open `doc/html/index.html` for reading the documentation.
+
+To correctly view the list of supported XEPs, a local webserver is needed, see the [DOAP rendering documentation][doap-rendering] for details.
+
+## Copyright
+
+QXmpp is [REUSE-compatible][reuse].
+Thus, you need to add an appropriate copyright header to each new file.
+If do significant changes to a file (e.g. no search and replace, typo fixes or just adding of pure
+non-copyrightable data like XML namespaces), you may add yourself as a copyright holder in the
+copyright header. This is recommended for large changes.
+
+If the file does not allow such a header, add a `.license` file for the copyright information.
+
+[doap-rendering]: /doc/doap-rendering/README.md
+[reuse]: https://api.reuse.software/info/github.com/qxmpp-project/qxmpp

README.md

@@ -3,6 +3,9 @@ SPDX-FileCopyrightText: 2009 Manjeet Dahiya <[email protected]>
 
 SPDX-License-Identifier: CC0-1.0
 -->
+
+# QXmpp - Cross-platform C++/Qt XMPP library
+
 <h1 align="center">
 <picture>
     <img alt="QXmpp logo" src="./logo.svg" height="150">
@@ -32,105 +35,104 @@ SPDX-License-Identifier: CC0-1.0
     <a href="https://liberapay.com/QXmpp/donate">
         <img alt="Donate using Liberapay" src="https://img.shields.io/liberapay/patrons/QXmpp.svg?logo=liberapay">
     </a>
+    <a href="https://api.reuse.software/info/github.com/qxmpp-project/qxmpp">
+        <img alt="REUSE status" src="https://api.reuse.software/badge/github.com/qxmpp-project/qxmpp">
+    </a>
 </p>
 
 QXmpp is a cross-platform C++ XMPP client and server library. It is written
-in C++ and uses Qt framework.
-
-QXmpp strives to be as easy to use as possible, the underlying TCP socket, the
-core XMPP RFCs (RFC6120 and RFC6121) and XMPP extensions have been nicely
-encapsulated into classes. QXmpp is ready to build XMPP clients complying with
-the [XMPP Compliance Suites 2022][xmpp-compliance] for IM and Advanced Mobile.
-It comes with full API documentation, automatic tests and some examples.
+in C++ and uses the Qt framework.
 
-QXmpp uses Qt extensively, and as such users need to a have working knowledge of
-C++ and Qt basics (Signals and Slots and Qt data types).
+QXmpp strives to be as easy to use as possible. The underlying TCP socket, the core XMPP RFCs
+(RFC6120 and RFC6121) and the [supported XMPP extensions][xeps] have been nicely encapsulated in
+classes.
+With QXmpp, it is possible to build XMPP clients complying with the
+[XMPP Compliance Suites 2022][xmpp-compliance] for IM and Advanced Mobile.
+It comes with full API documentation, automatic tests and examples.
 
-Qt is the only third party library which is required to build QXmpp, but
-libraries such as GStreamer enable additional features.
+QXmpp uses Qt extensively. Thus, users need to have a good knowledge of C++ and Qt basics
+(including the concept of signals/slots and Qt's data types).
+Qt is the only third party library required to build QXmpp, but libraries such as GStreamer enable
+additional features.
 
-QXmpp is released under the terms of the GNU Lesser General Public License,
-version 2.1 or later.
+QXmpp is released under the terms of the GNU Lesser General Public License, version 2.1 or later.
 
-Building QXmpp
-==============
+## Building
 
-QXmpp requires Qt 5.15 or Qt 6.0 or higher with SSL enabled.
-It uses CMake as build system.
+QXmpp requires **Qt 5.15** or **Qt 6.0 or higher** with SSL enabled.
 
-Build from command line:
-
-    mkdir build
-    cd build
-    cmake ..
-    cmake --build .
+You can build QXmpp with CMake:
+```
+mkdir build
+cd build
+cmake ..
+cmake --build .
+```
 
 You can pass the following arguments to CMake:
 
-    BUILD_SHARED                  to build with shared type library, otherwise static (default: true)
-    BUILD_DOCUMENTATION           to build the documentation, requires Doxygen (default: false)
-    BUILD_EXAMPLES                to build the examples (default: true)
-    BUILD_TESTS                   to build the unit tests (default: true)
-    BUILD_INTERNAL_TESTS          to build the unit tests testing private parts of the API (default: false)
-    BUILD_OMEMO                   to build the OMEMO module (default: false)
-    WITH_GSTREAMER                to enable audio/video over jingle (default: false)
-    QT_VERSION_MAJOR=5/6          to build with a specific Qt major version (default behaviour: prefer 6)
-
-For building the OMEMO module [additional dependencies](src/omemo/README.md)
-are required.
-
-Installing QXmpp
-================
-
-After building QXmpp, you can install the Headers, Libraries
-and Documentation using the following command:
+Option | Default | Description
+---|---|---
+`BUILD_SHARED` | `ON` | Build as shared library, otherwise static
+`BUILD_DOCUMENTATION` | `ON` | Build documentation, requires Doxygen
+`BUILD_EXAMPLES` | `ON` | Build examples
+`BUILD_TESTS` | `ON` | Build unit tests
+`BUILD_INTERNAL_TESTS` | `OFF` | Build unit tests testing private parts of the API
+`BUILD_OMEMO` | `OFF` | Build the [OMEMO module][omemo]
+`WITH_GSTREAMER` | `OFF` | Enable audio/video over Jingle
+`QT_VERSION_MAJOR=5/6` | | to build with a specific Qt major version, prefers Qt 6 if undefined
 
-Install from command line:
+For example, to build without unit tests you could do:
+```
+cmake .. -DBUILD_TESTS=OFF
+```
 
-    cmake --build . --target install
+## Installing
 
-Examples
-========
+After building QXmpp, you can install it using the following command:
+```
+cmake --build . --target install
+```
 
-Look at the example directory for various examples. Here is a description of
-a few.
+## Examples
 
-* *example_0_connected*
-This example just connects to the xmpp server and start receiving presences
-(updates) from the server. After running this example, you can see this user
-online, if it's added in your roster (friends list).
+There are various [examples][examples] in order to quickly start using QXmpp.
 
-* *example_1_echoClient*
-This is a very simple bot which echoes the message sent to it. Run this
-example, send it a message from a friend of this bot and you will
-receive the message back. This example shows how to receive and send messages.
+### `example_0_connected`
 
-Documentation
-=============
+This example connects to the XMPP server and starts receiving presences from the server.
+You can see whether the user is online and if the user is in your roster (contact list).
 
-You can find the API documentation for the latest stable QXmpp version here:
+### `example_1_echoClient`
 
-https://doc.qxmpp.org/
+This is a very simple bot which echoes the message sent to it.
+The example helps to understand how to receive and send messages.
 
-The API documentation of the master branch is also available:
+## Documentation
 
-https://doc.qxmpp.org/qxmpp-dev/
+There is an API documentation for the [latest stable QXmpp version][qxmpp-documentation] and one
+for the [master branch][qxmpp-master-documentation].
 
-Supported Platforms
-===================
+## Supported Platforms
 
-It should work on all the platforms supported by Qt. For a complete list of
-platforms support by Qt, see:
+QXmpp should work on all [platforms supported by Qt][supported-platforms].
 
-https://doc.qt.io/qt-5/supported-platforms.html
+## Bugs
 
-How to report a bug
-===================
+If you think you have found a bug in QXmpp, we would like to hear about it.
+That way, we can fix it.
+Before [reporting a bug][issues], please check if the issue is already known at.
 
-If you think you have found a bug in QXmpp, we would like to hear about
-it so that we can fix it. Before reporting a bug, please check if the issue
-is already know at:
+## Contributing
 
-https://github.com/qxmpp-project/qxmpp/issues
+If you are interested in contributing to QXmpp, please have a look at our [contribution guidelines][contributing].
 
+[xeps]: https://doc.qxmpp.org/qxmpp-1/xep.html
+[contributing]: /CONTRIBUTING.md
+[examples]: /examples
+[issues]: https://github.com/qxmpp-project/qxmpp/issues
+[omemo]: /src/omemo/README.md
+[qxmpp-documentation]: https://doc.qxmpp.org
+[qxmpp-master-documentation]: https://doc.qxmpp.org/qxmpp-dev/
+[supported-platforms]: https://doc.qt.io/qt-5/supported-platforms.html
 [xmpp-compliance]: https://xmpp.org/extensions/xep-0459.html

doc/doap-rendering/README.md

@@ -6,6 +6,11 @@ SPDX-License-Identifier: CC0-1.0
 
 # DOAP rendering
 
-Run `doc/doap-rendering/update-xeplist.sh` to get the latest XEP metadata
-before building the documentation.
+Run `doc/doap-rendering/update-xeplist.sh` to get the latest XEP metadata before building the documentation.
 
+You maybe need to open a local web server to display the list of supported XEPs in case your web browser prohibits the request to `doc/doap-rendering/doap.xsl`.
+Here is an example with Python's built-in web server and Firefox:
+```
+python3 -m http.server
+firefox http://0.0.0.0:8000/xep.html
+```

utils/pre-commit.sh

@@ -0,0 +1,9 @@
+#!/bin/sh -e
+
+# SPDX-FileCopyrightText: 2023 Melvin Keskin <[email protected]>
+#
+# SPDX-License-Identifier: CC0-1.0
+
+# This script runs all Git pre-commit hook scripts.
+
+git-clang-format

utils/setup-hooks.sh

@@ -0,0 +1,11 @@
+#!/bin/sh
+
+# SPDX-FileCopyrightText: 2023 Melvin Keskin <[email protected]>
+#
+# SPDX-License-Identifier: CC0-1.0
+
+# This script sets up useful git hooks in the local repository.
+
+REPO_ROOT=$(dirname "$(readlink -f "${0}")")/..
+
+cp $REPO_ROOT/utils/pre-commit.sh .git/hooks/pre-commit