Merge branch 'master' into debian/master

1 files changed, 52 insertions, 5 deletions

diff --git a/DEVELOPMENT.md b/DEVELOPMENT.md
index 79005a9..a2ec6a2 100644
--- a/DEVELOPMENT.md
+++ b/DEVELOPMENT.md
@@ -1,8 +1,7 @@
 # MIDIMonster development guide
 
 This document serves as a reference for contributors interested in the low-level implementation
-of the MIDIMonster. It is currently a work in progress and will be extended as problems come
-up and need solving ;)
+of the MIDIMonster. It will be extended as problems come up and need solving ;)
 
 ## Basics
 
@@ -19,6 +18,7 @@ in spirit rather than by the letter.
 * Commit messages should be in the imperative voice ("When applied, this commit will: ").
 * The working language for this repository is english.
 * External dependencies are only acceptable when necessary and available from package repositories.
+	* Note that external dependencies make OS portability complicated
 
 ### Code style
 
@@ -43,8 +43,55 @@ in spirit rather than by the letter.
 * Avoid `atoi()`/`itoa()`, use `strto[u]l[l]()` and `snprintf()`
 * Avoid unsafe functions without explicit bounds parameters (eg. `strcat()`). 
 
-# Build pipeline
+## Repository layout
 
-# Architecture
+* Keep the root directory as clean as possible
+	* Files that are not related directly to the MIDIMonster implementation go into the `assets/` directory
+* Prefer vendor-neutral names for configuration files where necessary
 
-# Debugging
+## Build pipeline
+
+* The primary build pipeline is `make`
+
+## Architecture
+
+* Strive to make backends platform-portable
+	* If that is not possible, try to keep the backend configuration compatible to other backends implementing the same protocol
+* If there is significant potential for sharing functionality between backends, consider implementing it in `libmmbackend`
+* Place a premium on keeping the MIDIMonster a lightweight tool in terms of installed dependencies and core functionality
+	* If possible, prefer a local implementation to one which requires additional (dynamic) dependencies
+
+## Language & Communication 
+
+* All visible communication (ie. error messages, debug messages) should be complete, correct english sentences
+* Strive for each output to have a concrete benefit or information to the reader
+	* Corollary: If nothing happens, don't send output
+		* Debug messages are somewhat exempt from this guideline
+* For error messages, give enough context to reasonably allow the user to either track down the problem or report a meaningful issue
+
+# Packaging
+
+Packaging the MIDIMonster for release in distributions is an important task. It facilitates easy access to
+the MIDIMonster functionality to a wide audience. This section is not strictly relevant for development, but touches
+on some of the same principles.
+
+As the MIDIMonster is a tool designed for interfacing between several different protocols, applications and
+other tools, to use "all" functionality of the MIDIMonster would imply installing additional software the user
+might not actually need. This runs counter to our goal of staying a lightweight tool for translation and control.
+
+The recommended way to package the MIDIMonster for binary distribution would be to split the build artifacts into
+multiple packages, separating out the heavier dependencies into separately installable units. If that is not an option,
+marking external dependencies of backends as `optional` or `recommended` should be preferred to having them required
+to be installed.
+
+Some backends have been marked optional in the repository and are only built when using `make full`.
+
+The recommended grouping into packaging units is as follows (without regard to platform compatibility, which
+may further impact the grouping):
+
+* Package `midimonster`: Core, Backends `evdev`, `artnet`, `osc`, `loopback`, `sacn`, `maweb`, `openpixelcontrol`, `rtpmidi`, `visca`, `mqtt`
+	* External dependencies: `libevdev`, `openssl`
+* Package `midimonster-programming`: Backends `lua`, `python`
+	* External dependencies: `liblua`, `python3`
+* Package `midimonster-media`: `midi`, `jack`, `ola`
+	* External dependencies: `libasound2`, `libjack-jackd2`, `libola`