Improve COMPILING and CONTRIBUTING files

COMPILING.md

@@ -1,22 +1,29 @@
+# Compiling Jamulus
+
 ## Points to note
 
-- Jamulus can be compiled for Linux, Windows and macOS. However, the preferred method of supporting these platforms is to use the binaries generated by the autobuild process in the Jamulus repository.
+- Jamulus can be compiled for Linux, Windows and macOS. However, the preferred method of supporting these platforms is to use the [binaries generated by the autobuild process](https://github.com/jamulussoftware/jamulus/releases/latest) in the Jamulus repository.
 - For unattended installs, see the contributed [installation scripts](https://github.com/jamulussoftware/installscripts)
+- The [Autobuild scripts](https://github.com/jamulussoftware/jamulus/tree/master/.github/autobuild) although only optimized to be used by the CI, might help you understand the process of setting up a build environment
 - There are reports from people who successfully compile and run Jamulus on BSDs.
 - Android and iOS are not officially supported.
 
 ---
 
 ## Download sources
 
-For .tar.gz [use this link](https://github.com/jamulussoftware/jamulus/archive/latest.tar.gz) to download the latest release
+First of all, you need to get the Jamulus source code. You can either download it manually or use git:
 
-For .zip [use this link](https://github.com/jamulussoftware/jamulus/archive/latest.zip)
+- For .tar.gz [use this link](https://github.com/jamulussoftware/jamulus/archive/latest.tar.gz) to download the latest release
+- For .zip [use this link](https://github.com/jamulussoftware/jamulus/archive/latest.zip)
+- If you use `git`, install it and then run `git clone git@github.com:jamulussoftware/jamulus` in Terminal to get the bleeding edge version directly from GitHub.
 
 ## Linux
 
 ### Install dependencies
 
+On Debian 11+ you can install the dependencies by issuing the following command: `sudo apt-get -qq --no-install-recommends -y install devscripts build-essential debhelper fakeroot libjack-jackd2-dev qtbase5-dev qttools5-dev-tools`
+
 On Ubuntu-based distributions 18.04+, Debian 9+, and Raspberry Pi OS:
 
 - build-essential
@@ -26,6 +33,8 @@ On Ubuntu-based distributions 18.04+, Debian 9+, and Raspberry Pi OS:
 - qttools5-dev-tools
 - libjack-jackd2-dev
 
+**Note:** The exact dependencies might be different for older distributions. See [this comment by softins](https://github.com/jamulussoftware/jamulus/pull/2267#issuecomment-1022127426)
+
 ### On Fedora 33+
 
 - qt5-qtdeclarative-devel
@@ -64,47 +73,56 @@ make
 sudo make install # optional
 ```
 
-To control the server with systemd, see this [unit file example](https://github.com/jamulussoftware/jamulus/blob/master/distributions/debian/jamulus-headless.service). See also runtime [configuration options](https://jamulus.io/wiki/Running-a-Server#command-line-options), and [this manual](https://jamulus.io/wiki/Server-Linux).
+To control the server with systemd, runtime options and similar, refer to the [Server manual](https://jamulus.io/wiki/Server-Linux).
 
 ---
 
 ## Windows
 
-You will need [Qt](https://www.qt.io/download)
+### Install dependencies
+
+Install [Qt](https://www.qt.io/download) e.g. via the official installer.
 
+**Note:**
 - Use the free GPLv2 license for Open Source development
 - Select Components during installation: Expand the Qt section, find the matching version, preferrably **Qt 5.15.2**, and add the compiler components for your compiler, e.g., `MSVC 2019 32-bit/64-bit` for Visual Studio 2019
-- [ASIO development files](https://www.steinberg.net/en/company/developer.html)
 
-### Compiling and building installer
+If you build with *JACK* support, install JACK via coco: `choco install --no-progress -y jack`
+If you build with ASIO support, you'll need the [ASIO development files](https://www.steinberg.net/en/company/developer.html). Please ensure you read the ASIO-SDK licensing terms and register with Steinberg if necessary.
 
-Most users will probably want to use this method:
+### Compiling and building installer
 
 1. Open PowerShell
 1. Navigate to the `jamulus` directory
 1. To allow unsigned scripts, right-click on the `windows\deploy_windows.ps1` script, select properties and allow the execution of this script. You can also run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser`. (You can revert this after having run this script. For more information see the [Microsoft PowerShell documentation page](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.security/set-executionpolicy)).
-1. Edit the $QtCompile32 and $QtCompile64 variables.
+1. Edit the $QtCompile32 and $QtCompile64 variables if needed
 1. Run the Jamulus compilation and installer script in PowerShell: `.\windows\deploy_windows.ps1`.
 1. You can now find the Jamulus installer in the `.\deploy` directory.
 
 ### Compiling only
 
 1. Create a folder under `\windows` called ASIOSDK2
-1. Download the [ASIOSDK](https://www.steinberg.net/asiosdk), open the top level folder in the .zip file and copy the contents into `[\path\to\jamulus\source]\windows\ASIOSDK2` so that, e.g., the folder `[\path\to\jamulus\source]\windows\ASIOSDK2\common` exists
+1. Download the [ASIOSDK](https://www.steinberg.net/asiosdk) if not already done, open the top level folder in the .zip file and copy the contents into `[\path\to\jamulus\source]\windows\ASIOSDK2` so that, e.g., the folder `[\path\to\jamulus\source]\windows\ASIOSDK2\common` exists
 1. Open Jamulus.pro in Qt Creator, configure the project with a default kit, then compile & run
 
 ---
 
 ## macOS
 
-You will need XCode and Qt as follows:
+### Install dependencies
+
+You will need Xcode and Qt.
+
+First, install [Xcode from the Mac AppStore](https://apps.apple.com/us/app/xcode/id497799835?mt=12). Then [install homebrew](https://brew.sh/).
+
+After that you can install Qt via homebrew:
 
 ```shell
 brew install qt5
 brew link qt5 --force
 ```
 
-### Generate XCode Project file
+### Generate Xcode Project file
 
 `qmake -spec macx-xcode Jamulus.pro`
 
@@ -137,14 +155,20 @@ Schemes:
 
 Will build the file and make it available in `./Release/Jamulus.app`
 
+If you want to build the installer, please run the `deploy_mac.sh` script: `./mac/deploy_mac.sh`. You'll find the installer in the deploy/ folder.
+
+---
+
 ## iOS
 
 1. Install [Xcode from the Mac AppStore](https://apps.apple.com/us/app/xcode/id497799835?mt=12)
-2. [Download and install qt5 with the Qt Installer](https://www.qt.io/download) (not homebrew). Explicitly select iOS when choosing the Qt version
+2. [Download and install Qt5 with the Qt Installer](https://www.qt.io/download) (not homebrew). Explicitly select iOS when choosing the Qt version
 3. Go to the folder of the Jamulus source code via terminal and run `/path/to/qt/5.15.2/ios/bin/qmake -spec macx-xcode Jamulus.pro` to generate an .xcodeproject file
 4. Open the generated .xcodeproject in Xcode
 5. Go to the Signing & Capabilities tab and fix signing errors by setting a team. Xcode will tell you what you need to change.
 
+**Note:**
+
 - If have a free Apple Developer Account, you can use it as a "Personal Team":
 - Set it up under Xcode Menu->Preferences->Accounts.
 - Then choose a Bundle Identifier at your choice in the relevant field in the "General" Tab (in section "Identity")
@@ -157,6 +181,8 @@ Will build the file and make it available in `./Release/Jamulus.app`
 9. Before being able to start Jamulus on your device, you'll have trust your developer profile in the device's Settings under General>Profiles & Device Management. For more information [see the guide by osxdaily](https://osxdaily.com/2021/05/07/how-to-trust-an-app-on-iphone-ipad-to-fix-untrusted-developer-message/)
 10. After a week you might need to restart from step 6 to continue to run Jamulus on iOS, unless you are paying for the Apple developer programme.
 
+---
+
 ## Android
 
 - Install Qt, including the Android support from the Qt installer

CONTRIBUTING.md

@@ -1,54 +1,50 @@
 # Want to contribute some code?
 
-## We’d really appreciate your support!
+We’d really appreciate your support! In order to keep things organized, please make sure you understand the following.
 
 - If the [Github issue](https://github.com/jamulussoftware/jamulus/issues) for your feature/bug fix already exists, write a message in that issue saying you want to work on it.
 - Otherwise, please [post on the GitHub Discussions](https://github.com/jamulussoftware/jamulus/discussions) and say that you are planning to do some coding and explain why. Then we can discuss the specification.
-- Please only start coding after we have agreed to a specification to avoid putting lots of work into something which may not get accepted later.
+- To avoid putting lots of work into something which may not get accepted later, please start coding after we have agreed to a specification.
 
 ## Jamulus project/source code general principles
 
-### Stability
+### 1. Stability
 
-This has been, and must continue to be, the most important requirement. It is particularly important for use cases such as the Worldjam where instability during a live performance would be unacceptable. The following two principles are designed to support this principle.
+Stability has been, and must continue to be, the most important requirement. In particular, instabilities during live performances such as WorldJam are not acceptable. The following principles are designed to support this.
 
-### [Keep it Simple and Stupid](https://en.wikipedia.org/wiki/KISS_principle) and [Do One Thing and Do It Well](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well)
+### 2. [Keep it Simple and Stupid](https://en.wikipedia.org/wiki/KISS_principle) and 3. [Do One Thing and Do It Well](https://en.wikipedia.org/wiki/Unix_philosophy#Do_One_Thing_and_Do_It_Well)
 
-If a feature or function can be achieved in another way by another system or method, then that is preferable to building that feature into Jamulus.
+If a feature or function can be achieved in another way by another system or method, then that is preferable instead of building that feature into Jamulus. Consider having a look at e.g. the [JSON-RPC](https://github.com/jamulussoftware/jamulus/blob/master/docs/JSON-RPC.md) API which allows you to communicate with the client and server from the outside.
 
 ### Source code consistency
 
-- Respect the existing code style: Tab size=4, insert spaces.
-- Space before and after `(` and `)`, except no space between `)` and `;`, and no space before an empty `()`.
-- All bodies of `if`, `else`, `while`, `for`, etc., to be enclosed in braces `{` and `}`, on separate lines.
+Our CI will fail and tell you about styling violations.
 
-You can use your editor's or IDE's clang-format support to accomplish that.
-On the command line, you can run `make clang_format` to do the same before committing.
+To keep a consistent coding style, please install `clang-format` on your PC and run it before committing.
 
-Do not use diff/patch to send your code changes but create a Github fork of the Jamulus code and create a Pull Request when you are done.
+There are multiple ways to run clang-format:
 
-Please run a local build test. Make sure there are no errors. After opening a pull request, keep an eye on the CI checks for quality or compile issues and fix them as required.
+- Use your editor's or IDE's clang-format support to accomplish that.
+- Via make: after running `qmake Jamulus.pro`, run `make clang_format`
+- Manually: run `clang-format -i <path/to/changed/files>`
 
-If there are conflicts with jamulussoftware/jamulus showing when you go to raise the pull request, resolve those locally:
+#### Style definition
 
-```shell
-git checkout master ;# checkout your local master
-git pull upstream master --tags ;# refresh from jamulussoftware/jamulus (i.e. use your upstream remote name)
-git push --tags --force ;# update your fork's master
-git checkout - ;# back to your working branch
-git rebase master ;# replay your changes onto the latest code
-git push --force ;# update your working branch on your fork
-```
+Please see the [.clang_format file](https://github.com/jamulussoftware/jamulus/blob/master/.clang-format) in the root folder. In short:
+
+- Respect the existing code style: Tab size=4, insert spaces.
+- Space before and after `(` and `)`, except no space between `)` and `;`, and no space before an empty `()`.
+- All bodies of `if`, `else`, `while`, `for`, etc., to be enclosed in braces `{` and `}`, on separate lines.
 
 ### Supported platforms
 
 We support the following platforms and versions:
 
 - Windows 7 or higher
-- macOS <!-- Which versions? -->
-- Ubuntu Linux 18.04 or later, Debian 10 or later, most Linux flavors with recent enough Qt versions
-  <!-- Do we support BSD? I think a recent discussion was about FreeBSD? -->
-  <!-- Should we already list Android? If so, what platforms/versions? -->
+- macOS 10.10 or higher
+- Ubuntu 18.04 or later, Debian 10 or later, most Linux flavors with recent enough Qt versions
+
+Android and iOS are not officially supported, however, please ensure not to break their build.
 
 Please try to avoid breaking any of them by introducing platform-specific code. Check to see if any newly introduced Qt calls are available in the minimum supported Qt version, which is currently 5.9. Note that code _style_ in a file may be Qt 4.x, and while you should normally stick to existing style if making large-scale changes, then updating to Qt 5.9 style is encouraged.
 Keep all code compatible to C++11.
@@ -59,9 +55,28 @@ If your code requires new dependencies, be sure that those are available on all
 
 ### User experience
 
-Jamulus is used by people all over the world with different backgrounds and knowledge. Features and language should be user focused.
-The Jamulus project has a [style and tone guide](https://jamulus.io/contribute/Style-and-Tone) which you should follow to remain consistent.
-Features should be usable in the sense that they act as expected to somebody who does not have a technical background.
+Jamulus is used by people all over the world with different backgrounds and knowledge. Therefore, think user focused.
+
+- Features should be usable in the sense that they act as expected to somebody who does not have a technical background.
+- Make sure you follow the [style and tone guide](https://jamulus.io/contribute/Style-and-Tone) to remain consistent.
+
+### Submitting code
+
+- Create a Github fork of the Jamulus code and create a Pull Request when you are done. Please don't use diff/patch to send your code changes. GitHub can be confusing, so feel free to ask for help.
+- Please run a local (build/feature) test to ensure there are no errors. After opening a pull request, keep an eye on the CI checks for quality or compile issues and fix them as required.
+
+#### Updating a PR/fixing conflicts
+
+If there are conflicts with jamulussoftware/jamulus showing when you raise your pull request or are requested to "rebase" your work, do so as follows:
+
+```shell
+git checkout master ;# checkout your local master
+git pull upstream master --tags ;# refresh from jamulussoftware/jamulus (i.e. use your upstream remote name. If you haven't set it up yet, add it via 'git remote add upstream git@github.com:jamulussoftware/jamulus')
+git push --tags --force ;# update your fork's master
+git checkout - ;# back to your working branch
+git rebase master ;# replay your changes onto the latest code (and fix conflicts if needed)
+git push --force ;# update your working branch on your fork
+```
 
 ### Ownership
 
@@ -71,7 +86,7 @@ So as to reduce effort for others in understanding a PR or an Issue, authors are
 
 ### Documentation/Acknowledgements
 
-Each new feature or bug fix must be documented in the ChangeLog. Please provide a single-sentence suggestion for that as part of your pull request description. Do not modify the ChangeLog file as part of your PR as it will lead to conflicts.
+Each new feature or bug fix must be documented in the ChangeLog. Please provide a single-sentence suggestion for that as part of your pull request description after the `CHANGELOG: ` line. Do not modify the ChangeLog file as part of your PR as it will lead to conflicts.
 
 If you are a first-time contributor/translator, please add yourself to the contributor/translator list in the About dialog of the Jamulus software (see in `src/util.cpp` in the constructor function `CAboutDlg::CAboutDlg()`).
 
@@ -83,4 +98,4 @@ The git master branch is protected to require at least two reviews by the main d
 
 ## Want to get involved in other ways?
 
-We always need help with documentation, translation and anything else. Have a look at our [overview for contributors](https://jamulus.io/wiki/Contribution).
+We always need help with documentation, [translation](https://github.com/jamulussoftware/jamulus/blob/master/docs/TRANSLATING.md) and anything else. Feel free to look at the [Website repository](https://github.com/jamulussoftware/jamuluswebsite) or get involved in fixing issues from the [issue tracker](https://github.com/jamulussoftware/jamulus/issues).