Compatibility is a complex issue, but we do our best in to maintaining three types of compatibilities between two any two sequential versions of SSLR (e.g. between 1.17 and 1.18, but not between 1.16 and 1.18):
- binary compatibility: we don't guarantee that your code can be linked with new version without recompilation, however for most releases this might be possible;
- source compatibility: in most cases (see below) you should be able to recompile your code with a newer version of SSLR without any changes;
- behavioral compatibility: in most cases (see below) your code will behave exactly as it did with the previous version of SSLR without any changes.
We can't guarantee that your code can be compiled or linked with new version of SSLR and will behave exactly as before the upgrade in the following situations:
- You use internal classes or interfaces, i.e. those that are located under package "org.sonar.sslr.internal".
- You create instances or subclasses of classes, which are not intended for this. Such classes are marked by Javadoc ("This class is not intended to be instantiated or subclassed by clients").
- You implement interfaces , which are not intended for this. Such interfaces are marked by Javadoc ("This interface is not intended to be implemented by clients").
- You use methods marked as internal. Such methods are marked by annotation "@VisibleForTesting" or by Javadoc ("For internal use only").
- You use beta code. Such code is marked by annotation "@Beta".
- You use deprecated code. Such code is marked by annotation "@Deprecated" and Javadoc.
We try to keep and maintain deprecated code as long as possible, but generally it can may be removed in a next the release after the one , when in which it was marked as deprecated. That's why highly recommended to not why we highly recommend not to jump over two versions at once, but perform upgrades in several steps - by one version per step. And Each such step should include the removal of uses of deprecated code. Thus, it is recommended to do an upgrade as soon as a new version is available. Recommended way to do one step is
Recommended upgrade steps:
- Recompile your code with the next version of SSLR. If it can't be compiled, then don't hesitate to inform us about this.
- Check release notes on release and upgrade about notes for the existence of behavioral incompatibilities (see below). If there are any, then you should fix them by following the instructions in the notes. Good coverage of your code by unit tests is highly recommended (SonarQube TM can help you to enforce this), so you will be able to perform tests to verify that it behaves exactly as before upgrade. If not, then don't hesitate to ask for help.
- Remove uses of deprecated code by following instructions from the instructions you'll find in the deprecation Javadocs (SonarQube TM can help you to find such code). And don't forget to execute tests to verify that regressions were not introduced by such changes.
- Source: sonar-channel from SonarQube is merged into SSLR. Change the package name "org.sonar.channel" into "org.sonar.sslr.channel" for lexing purposes. Depend on sslr-testing-harness instead of sonar-testing-harness for the lexer unit tests.
- Deprecation: The preprocessor API classes Preprocessor, PreprocessorAction and PreprocessingDirective were deprecated with no drop-in replacements. There no longer will be a unified API for preprocessors. Note: Not always possible to fix in 1.20 due to SSLR-359
- Deprecation: The text API package "org.sonar.sslr.text" has been deprecated with no drop-in replacements. There no longer will be a common way to track the location of preprocessed source code.
- Behavioral: Parse tree was removed from the parse error report.
- Source: Deprecated hamcrest matchers were removed in preference to Fest-assertions.
- Behavioral: No No difference between usual grammar rule and "recovery rule" - both will be presented in AST and so can be handled via AST visitor. Thus ParseErrorCheck in SonarQube TM plugins must be reworked, if plugin uses "recovery rule".
- Behavioral: Modifications made in grammar do not affect lexerless parser, which was created before those modifications.
- Behavioral: Previously was possible to execute parser with grammar, which contains references on undefined rules, but now this is forbidden.
- Behavioral: Replace AuditListener by AstScannerExceptionHandler to subscribe to errors
- Deprecation: Old ways to construct Grammars were marked as deprecated - use Builders instead.
- Deprecation: Replace "GrammarFunctions.Standard.or(" by "GrammarFunctions.Standard.firstOf(". In most cases you should be able to do this by using "find text and replace".
- Deprecation: Replace the hamcrest parse() and notParse() matches by Fest ones: Use a global regular expression based find & replace: "assertThat\(p, parse\((.*?)\)\);" by ".matches\($1\)" and add the assertThat(Parser) and final semicolon manually. Do the same for notParse().
- Source: Replace artifactId "sslr-devkit" by "sslr-toolkit".