The {@link com.oracle.truffle.tutorial Truffle Tutorial} gives you the best introduction to Truffle: the Open Source framework for implementing programming languages with very high performance, Java embedding, language interoperation, debugging, and general tooling support.
The Truffle 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.
On the other hand the Truffle 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:
By deprecating parts of API while keeping them functional we are giving users of the Truffle 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.