Usage guide and contribution docs (#180)

Author: mr-smidge

CONTRIBUTING.md

@@ -0,0 +1,61 @@
+Contributing to libdjinterop
+============================
+
+If you are interested in contributing to `libdjinterop`, thank you!
+
+The easiest way to contribute is to look at the
+[issues list](https://github.com/xsco/libdjinterop/issues) and see if there is
+anything that you might like to try.
+
+Although `libdjinterop` is a C++ library, there are usually both coding and
+non-coding tasks available.  All contributions are hugely appreciated!
+
+C++ Style Guide
+---------------
+
+C++ coding conventions in `libdjinterop` broadly follow the
+[Core C++ Guidelines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines)
+from ISO C++.
+
+Furthermore, there is a [.clang-format](.clang-format) file in the repository,
+and all code contributions should conform to this.
+
+Perhaps one day there will be more opinionated formatting/linting, or indeed
+a pre-commit hook to enforce it.
+
+Unit Testing
+------------
+
+High unit test coverage is _strongly encouraged_ for all C++ code contributions.
+It may become a mandatory requirement one day.
+
+External Dependencies
+---------------------
+
+Introducing any additional external dependencies into `libdjinterop` is a big
+decision that requires proper consideration.  The aim is for the library to be
+built and compiled with minimal additional requirements, in order to make
+wider adoption as easy as possible.
+
+For an external dependency to be considered, ideally it should be readily
+available on all stable versions of each target operating system, as well as
+be a stable and mature library.
+
+For dependencies that do not meet these criteria, another option is to 'vendor'
+the dependencies into the codebase under the [ext/](ext) directory hierarchy.
+
+OS Compatibility
+----------------
+
+The library is expected to compile on:
+
+* Windows - all supported versions
+* Linux:
+  * Ubuntu - all LTS versions
+  * Red Hat and friends - all supported versions
+  * Arch Linux
+* macOS - all recent versions
+
+The biggest user of this library is undoubtedly the [Mixxx](https://mixxx.org)
+open source DJ application.  As such, it is a very sensible idea to ensure that
+the library always compiles on the operating systems that Mixxx targets too.

GUIDE.md

@@ -0,0 +1,85 @@
+Guide to libdjinterop
+=====================
+
+This documentation provides an introductory guide to the public API of
+`libdjinterop`, and provides information on how to get started using it.
+
+High-level vs. Low-level APIs
+-----------------------------
+
+The library offers so-called "high-level" and "low-level" APIs, which serve
+different purposes.
+
+Low-level APIs
+--------------
+
+The low-level APIs provides a very thin wrapper over a specific DJ database
+library format.  A low-level API exposes all the peculiarities, details, and
+expressivity of that format, and does not offer any abstractions beyond
+presenting a C++ library interface.
+
+There are multiple low-level APIs, one for each type of DJ library format.
+There can also be multiple low-level APIs to cover occasions where a library
+undergoes a significant change to its schema (e.g. Engine 1.x and Engine 2.x
+are distinct low-level APIs).
+
+Sometimes, a low-level API (or collection of them) offer utility functions that
+help the end user translate from common concepts into encodings or types that
+are specific to the low-level library format.  An example could be calculating
+the preferred size of a waveform for a given format.
+
+The current low-level APIs offered are listed below:
+
+| Low-level API | Include Path                                        |
+|---------------|-----------------------------------------------------|
+| Engine 2.x    | `#include <djinterop/engine/v2/engine_library.hpp>` |
+| Engine 3.x    | `#include <djinterop/engine/v3/engine_library.hpp>` |
+
+Note that there is no low-level API for Engine 1.x at present.  This is because
+when the library was first being written, Engine 1.x support was introduced
+directly into the high-level API without a low-level companion.  The low-level
+API was developed with the introduction of Engine 2.x, and because the 1.x
+library was effectively now deprecated, the effort was not undertaken to
+backport the idea to 1.x.  If a low-level API for Engine 1.x is important to
+you, please consider contributing!
+
+High-level API
+--------------
+
+The library offers a high-level API as well, with a very different purpose to
+that of the low-level APIs.  Whereas low-level APIs simply expose an underlying
+DJ library format in the form of a C++ API, the high-level API aims to:
+
+* Abstract over all format-specific aspects.
+* Offer a uniform interface, regardless of the underlying DJ library format.
+* Offer meaningful DJ library concepts, in the form of lightweight handles to
+  objects in the underlying DJ library, that can be read or updated.
+
+The primary concepts in the high-level API are:
+
+* _Database_, representing the overall DJ library.
+* _Track_, representing a lightweight handle to a track in the library.
+* _Track snapshot_, representing a collection of offline data read from a track
+  in the library.
+* _Crate_, representing an unordered list of related tracks.
+* _Playlist_, representing an ordered list of related tracks.
+
+Part of the challenge in developing `libdjinterop` is to ensure that the
+high-level API appropriately abstracts over all the different ways that the
+above concepts might be implemented in a real DJ library format.
+
+In reality, a DJ library that exists on disk is always of a specific format.
+As such, in order to create a new library or load an existing library with the
+intention of operating on it using the high-level API, it is always necessary
+to start with format-specific functions to do so:
+
+| Library Type | Include Path                             |
+|--------------|------------------------------------------|
+| Engine       | `#include <djinterop/engine/engine.hpp>` |
+
+
+Stable API/ABI
+--------------
+
+The library does not yet commit to offer either a stable API nor ABI.  This
+situation may change in the future as the library matures.

README.md

@@ -4,17 +4,11 @@ Overview
 `libdjinterop` is a C++ library that allows access to database formats used to
 store information about DJ record libraries.
 
-This library currently supports:
-
-* Engine Library, as used on "Prime"-series DJ equipment.
-
-Documentation can be viewed on [GitHub Pages](https://xsco.github.io/libdjinterop/)
-
 State of Support
 ================
 
-The library is currently in an early beta stage, and not all features are
-implemented yet.  It currently supports only the Engine Library format.
+The library is currently in development, and not all features are implemented
+yet.  It currently supports only the Engine Library format.
 
 What is supported:
 
@@ -29,7 +23,8 @@ What is supported:
 The library supports the following firmware and application versions:
 
 * Engine DJ OS from 1.0.3 to 4.3.3.
-  * Tested on Denon SC5000 and Numark Mixstream Pro. Other players (e.g. SC6000/M) may work, but this is currently untested.
+  * Tested on Denon SC5000 and Numark Mixstream Pro. Other players (e.g.
+    SC6000/M) may work, but this is currently untested.
 * Engine DJ Desktop (aka Engine Prime) from 1.0.1 to 4.3.0.
 
 What is not supported (yet):
@@ -41,8 +36,14 @@ What is not supported (yet):
 How Do I Use It?
 ================
 
-The library is not ready for prime-time yet, but if you are willing to read
-source code, example applications can be found in the `example` directory.
+If you are new to the library, see the [introductory guide](GUIDE.md) for an
+explanation of how the library is structured and how to get started.
+
+The [examples/](example) directory contains some small self-contained
+applications that use the library.
+
+Detailed reference documentation for the public API can be viewed on
+[GitHub Pages](https://xsco.github.io/libdjinterop/).
 
 How Do I Build It?
 ============================