# HG changeset patch
# User Jaroslav Tulach <jaroslav.tulach@oracle.com>
# Date 1445624564 -7200
# Node ID ad67d348e361e44b605c60b9477bf4a294f2f2a5
# Parent  096e2c0fd2dc2378364d09b76ec752c261e37778
Defining incompatible API change policy for development versions

diff -r 096e2c0fd2dc -r ad67d348e361 truffle/overview.html
--- a/truffle/overview.html	Thu Oct 22 21:07:03 2015 +0200
+++ b/truffle/overview.html	Fri Oct 23 20:22:44 2015 +0200
@@ -57,5 +57,33 @@
   <li><a target="_blank" href="http://ssw.jku.at/Research/Projects/JVM/Graal.html">Papers on Graal</a></li>
 </ul>
 
+<h4>Keeping Compatibility</h4>
+
+<p>
+The <b>Truffle</b> API values work of its adopters and as such it is developed
+with compatibility in mind. Methods and features are not removed and renamed
+randomly, without a notice and there is a binary compatibility testing framework
+in place to verify that.
+</p>
+<p>
+On the other hand the <b>Truffle</b> project is still young and needs a way
+to refine and change previously taken decisions. To balance the need between
+compatibility and give us a way to remove things from the API we following
+these rules:
+</p>
+<ul>
+    <li>Rather than removing/renaming or changing an API element (class, method,
+        field), mark it <em>deprecated</em>.</li>
+    <li>Make sure usage of such element can be replaced by non-deprecated ways</li>
+    <li>Keep such element working until next release</li>
+    <li>If possible provide automatic migration using Jackpot's META-INF/upgrade/ files</li>
+    <li>When new (major) release is out, remove it</li>
+</ul>
+<p>
+By deprecating parts of API while keeping them functional we are giving
+users of the <b>Truffle</b> API time to adjust to required
+changes and (under the assumption they pay attention to warnings in the code
+base) easily identify and migrate to more modern API alternatives.
+</p>
 </body>
 </html>