From c4546171fff6eca499bf5a0427e5bc436820cf0d Mon Sep 17 00:00:00 2001
From: Martin Dobias <wonder.sk@gmail.com>
Date: Sat, 6 Sep 2014 14:01:30 +0700
Subject: [PATCH] Start of doxygen page about API breaks

---
 doc/api_break.dox | 37 +++++++++++++++++++++++++++++++++++++
 doc/index.dox     |  2 ++
 2 files changed, 39 insertions(+)
 create mode 100644 doc/api_break.dox

diff --git a/doc/api_break.dox b/doc/api_break.dox
new file mode 100644
index 00000000000..c9f57ec4403
--- /dev/null
+++ b/doc/api_break.dox
@@ -0,0 +1,37 @@
+/*! \page api_break Backwards Incompatible Changes
+
+\tableofcontents
+
+The API of QGIS libraries is allowed to be changed just between major versions of QGIS. For example, there
+are various planned backwards incompatible changes between QGIS 1.8 and 2.0 because the version 2.0 is a new
+major version. After a release of a major version of QGIS (e.g. 2.0) the developer team is committed to maintain
+stable API for all subsequent minor releases (2.2, 2.4, ...). That roughly means we do not rename classes and methods,
+remove them nor change their semantics. Existing code should keep working when the user updates QGIS
+to another minor version (e.g. from 2.0 to 2.2), so all extensions of existing classes should be done in a manner that
+third party developers do not need to adjust their code to work properly with newer QGIS releases.
+
+Sometimes, however, we may need to break the API as a result of some code changes. These cases should be only exceptions
+and they should happen only after consideration and agreement of the development team. Backwards incompatible changes
+with too big impact should be deferred to a major version release.
+
+This page tries to maintain a list with incompatible changes that happened in previous releases.
+
+\section qgis_api_break_2_4 QGIS 2.4
+
+\subsection qgis_api_break_mtr Multi-threaded Rendering
+
+<ul>
+<li>QgsPluginLayer::draw() is now run in a background thread. It is recommended to implement newly added QgsPluginLayer::createMapRenderer()
+method instead of using QgsPluginLayer::draw().
+</ul>
+
+\section qgis_api_break_2_6 QGIS 2.6
+
+\subsection qgis_api_break_legend_refactoring Legend Refactoring
+
+<ul>
+<li>QgsComposerLegend::model() - not being used anymore. The model was replaced by one based on QgsLayerTreeModel class
+and is available in QgsComposerLegend::modelV2()
+</ul>
+
+*/
diff --git a/doc/index.dox b/doc/index.dox
index 7b2118bda64..cadeab8e697 100644
--- a/doc/index.dox
+++ b/doc/index.dox
@@ -24,6 +24,8 @@ the the documentation for offline use.
 
 \section index_APIStability Earlier versions of the API
 
+See \ref api_break for information about incompatible changes to API between releases.
+
 Earlier versions of the documentation are also available on the QGIS
 website: