Mercurial > hg > truffle
changeset 22324:ad67d348e361
Defining incompatible API change policy for development versions
author | Jaroslav Tulach <jaroslav.tulach@oracle.com> |
---|---|
date | Fri, 23 Oct 2015 20:22:44 +0200 |
parents | 096e2c0fd2dc |
children | 414e82b9fc35 |
files | truffle/overview.html |
diffstat | 1 files changed, 28 insertions(+), 0 deletions(-) [+] |
line wrap: on
line diff
--- 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>