DOCS(plugins): Document Mumble API increments

Describe necessary steps to implement a new API version for plugins.

1 files changed, 34 insertions, 0 deletions

diff --git a/docs/dev/IncrementingTheMumbleAPI.md b/docs/dev/IncrementingTheMumbleAPI.md
new file mode 100644
index 000000000..36327e2d6
--- /dev/null
+++ b/docs/dev/IncrementingTheMumbleAPI.md
@@ -0,0 +1,34 @@
+# Incrementing the Mumble API version
+
+## Overview
+[Plugins](/docs/dev/plugins/) are used to extend the Mumble client with custom functionality. They are compiled against multiple [header files](/plugins/) which
+contain all function and structure signatures that can be used by the plugin. If you are commiting breaking API changes (such as additions or deletions) to these function signatures
+on the Mumble side, the API version will probably have to be increased. This is done to ensure plugins will have access to these functions when they
+are compiled against the new API version, while old plugins, using previous API versions, will still work.
+
+## Instructions
+If your commit includes breaking API changes, the following steps have to be followed:
+
+1) Create a new ``Mumble_API_v_<MA>_<MI>_x.h`` file in [plugins/](/plugins/).
+	* Replace ``<MA>`` with the API major version and ``<MI>`` with the API minor version.
+	* Usually, you will have to increase the ``<MI>`` version by 1 compared to the previous latest version. So if the previous API string was ``1.2.0``, you would probably want to increase the second number by one and create the file ``MumbleAPI_v_1_3_x.h``.
+	* The last "patch" digit of the version string is reserved for non-breaking API changes such as small fixes. Since non-breaking changes do not require a major or minor API increment, we do not worry about the "patch" digit in this document.
+1) Make sure you correctly set the ``MUMBLE_PLUGIN_API_MAJOR_MACRO``, ``MUMBLE_PLUGIN_API_MINOR_MACRO`` and [include guard](https://en.wikipedia.org/wiki/Include_guard) to the new API version. 
+	* You probably want to set the ``MUMBLE_PLUGIN_API_PATCH_MACRO`` to ``0``.
+1) Rename the ``struct`` within the file to match the new API version string.
+	* There is a ``typedef`` at the end of the file which has to use the new ``struct`` name, too.
+1) Make your desired changes to the function signatures contained in the header file.
+1) Open the [MumbleAPI_structs.h](/src/mumble/MumbleAPI_structs.h) file and add your new API header file as first include.
+	* Move the previous first include, the last most recent API version, into the ``NO_AUXILIARY_DEFINITIONS`` section.
+	* This will make sure auxiliary variables and macros always contain the most recent version on the mumble side.
+1) Add an ``else`` case to the [Plugin.cpp](/src/mumble/Plugin.cpp) file in the ``Plugin::init`` method.
+	* You will want to return the newly created ``struct``, if the API version requested by the plugin matches your new one.
+1) Create a new function signature in [API.h](/src/mumble/API.h). It should return your new ``struct`` and be of the name ``getMumbleAPI_v_<MA>_<MI>_x``.
+1) Amend the previous ``API_v_<MA>_x_x.cpp`` file, or create a new one in [this folder](/src/mumble/).
+	* For the foreseeable future, reuse the previous cpp file. Creating a new cpp file will probably only be useful on extensive API re-designs.
+	* If you have created a new ``API_v_<MA>_x_x.cpp``, you must add it to the [CMakeLists.txt](/src/mumble/CMakeLists.txt).
+1) Implement the ``getMumbleAPI_v_<MA>_<MI>_x`` function inside the ``API_v_<MA>_x_x.cpp`` file and return a struct with all functions you want to expose in your API version.
+1) When adding a new function or new function signature, copy an existing "C FUNCTION WRAPPER" inside the ``API_v_<MA>_x_x.cpp`` file. That wrapper should then call your new function.
+1) Implement your new API changes in the ``API_v_<MA>_x_x.cpp`` file.
+	* If you change the signature of an old function, it is probably best to call the new function in the old implementation with default values.
+	* This way, old plugins will still be working more or less as expected.