Added breaking changes documentation to root folder of JUCE

BREAKING-CHANGES.txt

@@ -0,0 +1,83 @@
+JUCE breaking changes
+=====================
+
+
+Version 4.3.1
+=============
+
+Change
+------
+JUCE has changed the way native VST3/AudioUnit parameter ids are calculated
+
+Possible Issues
+---------------
+DAW projects with automation data written by an AudioUnit or VST3 plug-in built with pre JUCE 4.3.1 versions will load incorrectly when opened by an AudioUnit or VST3 built with JUCE versions 4.3.1 and later. Plug-ins using JUCE_FORCE_USE_LEGACY_IDS are not affected 
+
+Workaround
+----------
+Disable JUCE_USE_STUDIO_ONE_COMPATIBLE_PARAMETERS in the juce_audio_plugin_client module config page in the Projucer. For new plug-ins, be sure to use the default value for this property.
+
+Rationale
+--------
+JUCE needs to convert between its own JUCE parameter id format (strings) to the native parameter id formats of the various plug-in backends. For VST3 and AudioUnits, JUCE uses a hash function to generate a numeric id. However, some VST3/AudioUnit hosts (specifically Studio One) have a bug that ignore any parameters that have a negative parameter id. Therefore, the hash function for VST3/AudioUnits needed to be changed to only return positive-valued hashes.
+
+
+
+Version 4.3.0
+=============
+
+Change
+------
+A revised multi-bus API was released which supersedes the previously flawed multi-bus API - JUCE versions 4.0.0 - 4.2.4 (inclusive)
+
+Possible Issues
+---------------
+If you have developed a plug-in with JUCE versions 4.0.0 - 4.2.4 (inclusive), then you will need to update your plug-in to the new multi-bus API. Pre JUCE 4.0.0 plug-ins are not affected apart from other breaking changes listed in this document.
+
+Woraround
+---------
+None
+
+Rationale
+--------
+A flawed multi-bus API was introduced with JUCE versions 4.0.0 up until version 4.2.4 (inclusive) which was not API compatible with pre JUCE 4 plug-ins. JUCE 4.3.0 releases a revised multi-bus API which restores pre JUCE 4 API compatibility. However, the new multi-bus API is not compatible with the flawed multi-bus API (JUCE version 4.0.0 - 4.2.4).
+
+
+
+Change
+------
+JUCE now generates the AAX plug-in bus layout configuration id independent from the position as it appears in the Projucer’s legacy “Channel layout configuration” field.
+
+Possible Issues
+---------------
+ProTools projects generated with a < 4.3.0 JUCE versions of your plug-in, may load the incorrect bus configuration when upgrading your plug-in to >= 4.3.0 versions of JUCE. 
+
+Workaround
+----------
+Implement AudioProcessor’s getAAXPluginIDForMainBusConfig callback to manually override which AAX plug-in id is associated to a specific bus layout of your plug-in. This workaround is only necessary if you have released your plug-in built with a version previous to JUCE 4.3.0.
+
+Rationale
+--------
+The new multi-bus API offers more features, flexibility and accuracy in specifying bus layouts which cannot be expressed by the Projucer’s legacy “Channel layout configuration” field. The native plug-in format backends use the new multi-bus callback APIs to negotiate channel layouts with the host - including the AAX plug-in ids assigned to specific bus layouts. With the callback API, there is no notion of an order in which the channel configurations appear - as was the case with the legacy “Channel layout configuration” field - and therefore cannot be used to generate the AAX plug-in id. To remain backward compatible to pre JUCE 4.0.0 plug-ins, JUCE does transparently convert the legacy “Channel layout configuration” field to the new callback based multi-bus API, but this does not take the order into account in which the channel configurations appear in the legacy “Channel layout configuration” field.
+
+
+
+
+Version 4.2.1
+=============
+Change
+------
+JUCE now uses the paramID property used in AudioProcessorParameterWithID to uniquely identify parameters to the host
+
+Possible Issues
+---------------
+DAW projects with automation data written by an audio plug-in built with pre JUCE 4.2.1 will load incorrectly when opened by an audio plug-in built with JUCE 4.2.1 and later.
+
+Workaround
+----------
+Enable JUCE_FORCE_USE_LEGACY_IDS in the juce_audio_plugin_client module config page in the Projucer. For new plug-ins, be sure to disable this property.
+
+Rationale
+--------
+Each parameter of the AudioProcessor has an id associated so that the plug-in’s host can uniquely identify parameters. The id has a different data-type for different plug-in types (for example VST uses integers, AAX uses string identifiers). Before 4.2.1, JUCE generated the parameter id by using the index of the parameter, i.e. the first parameter had id zero, the second parameter had id one, etc. This caused problems for certain plug-in types where JUCE needs to add internal parameters to the plug-in (for example VST3 requires the bypass control to be a parameter - so JUCE automatically creates this parameter for you in the VST3 backend). This causes subtle problems if a parameter is added to an update of an already published plug-in. The new parameter’s id would be identical to the id of the bypass parameter in old versions of your plug-in, causing seemingly random plug-in bypass behaviour when user’s upgrade their plug-in. 
+Most plug-in backends differentiate between a parameter’s id an index, so this distinction was adopted starting with JUCE 4.2.1 by deriving the parameter’s unique id from the paramID property of AudioProcessorParameterWithID class.