Inital draft of @binaryCompatible proposal.

Author: DarkDimius

sips/pending/_posts/2017-01-13-binary-compatibility.md

@@ -0,0 +1,127 @@
+---
+layout: sip
+title: SIP XX - Improving binary compatibility with @binaryCompatible
+disqus: true
+---
+
+__Dmitry Petrashko__
+
+__first submitted 13 February 2017__
+
+## Introduction ##
+
+Scala is a language which evolves fast and thus made a decision to only promise binary compatibility across minor releases.
+At the same time, there is a demand to develop APIs that live longer than a major release cycle of Scala.
+This SIP introduces an annotation `@binaryCompatible` that checks that `what you write is what you get`.
+It will fail compilation in case emitted methods or their signatures 
+are different from those written by users. 
+As long as signatures of methods in source is not changed, `@binaryCompatible` annotated class 
+will be compatible across major version of Scala. 
+
+## Use Cases
+Dotty currently uses java defined interfaces as public API for SBT in order to ensure binary compatibility. 
+This interfaces can be replaced by `@binaryCompatible` annotated traits to reach the same goal.  
+
+
+## Design guideline
+`@binaryCompatible` is a feature which is supposed to be used by a small subset of ecosystem to be binary compatible across major versions of Scala.
+Thus this is designed as an advanced feature that is used rarely and thus is intentionally verbose. 
+It's designed to provide strong guarantees, in some cases sacrificing ease of use. 
+
+## Overview ##
+In order for a class or a trait to succeed compilation with `@binaryCompatible` annotation it has to be:
+  - defined on the top level;
+  - use a subset of Scala that during compilation does not require changes to public api of the class, including
+     - synthesizing new members, either concrete or abstract;
+     - changing binary signatures of existing members, either concrete or abstract;
+The `@binaryCompatible` does not change the compilation scheme of a class:
+ compiling a class previously annotated by `@binaryCompatible`, will produce the same bytecode with or without `@binaryCompatible` annotation. 
+
+Below are several examples of classes and traits that succeed compilation with `@binaryCompatible`
+```scala
+{% highlight scala %}
+@binaryCompatible
+trait AbstractFile {
+  /** @return The name of this file, note that two files may have the same name. */
+  def name(): String
+
+  /** @return The path of this file, this might be a virtual path of an unspecified format. */
+  def path(): String
+
+  /** @return If this is a real file on disk, a `java.io.File` that corresponds to this file.
+   *          Otherwise, an empty `Optional`.
+   */
+  def jfile(): Optional[File]
+}
+
+@binaryCompatible
+trait SourceFile extends AbstractFile {
+  /** @return The content of this file as seen by the compiler. */
+  def content(): Array[Char]
+}
+
+@binaryCompatible
+trait Diagnostic {
+  def message(): String
+
+  def level(): Int
+
+  def position(): Optional[SourcePosition]
+}
+
+@binaryCompatible
+object Diagnostic {
+  @static final val ERROR: Int = 2
+  @static final val WARNING: Int = 1
+  @static final val INFO: Int = 0
+}
+
+{% endhighlight %}
+```
+
+## Features that will fail compilation with `@binaryCompatible`
+
+  - lazy vals
+  - default methods
+  - default arguments
+  - case classes
+  - public fields
+  - constant types(both explicit and inferred)
+  - inline
+  
+  
+## `@binaryCompatible` and Scala.js
+
+Allowing to write API-defining classes in Scala instead of Java will allow to compile them with Scala.js, 
+which would have benefit of sharing the same source for two ecosystems.
+
+Scala.js currently is binary compatible as long as original bytecode compiled by Scala JVM is binary compatible.
+Providing stronger binary compatibility guarantees for JVM will automatically provide stronger guarantees for Scala.js.
+ 
+
+## Comparison with MiMa ##
+The Migration Manager for Scala (MiMa in short) is a tool for diagnosing binary incompatibilities for Scala libraries.
+MiMa allows to compare binary APIs of two already compiled classes and reports errors if APIs do not match perfectly.
+
+MiMa and `@binaryCompatible` complement each other, as `@binaryCompatible` helps to develop APIs that stay compatible 
+across major versions, while MiMa checks that previously published artifacts indeed use the same API.
+
+`@binaryCompatible` does not compare the currently compiled class or trait against previous version, 
+so introduction of new members won't be prohibited. This is a use-case for MiMa.
+  
+MiMa does not indicate how hard, if possible, would it be to maintain compatibility of a class across future versions of Scala.
+Multiple features of Scala, most notably lazy vals and traits, has been compiled diffently by different Scala versions
+making porting existing compiled bytecode across versions very hard. 
+MiMa would complain retroactively that the new version is incompatible to the old one, while `@binaryCompatible` would provide early notification. 
+
+## Compilation scheme ##
+No modification of typer or any existing phase is planned. The current proposed scheme introduces a late phase that runs before the very bytecode emission that checks that:
+ - classes and traits annotated as  `@binaryCompatible` are on the top level; 
+ - no non-private members where introduced inside classes and traits annotated as  `@binaryCompatible` by compiler using phase travel;
+ - no non-private members inside classes and traits annotated as  `@binaryCompatible` has changed their signature from the one written by developer.
+
+The current prototype is implemented for Dotty and supports everything descibed in this SIP. 
+The implementation is simple with less than 50 lines of non-boilerplate code. 
+The current implementation has a scope for improvement of error messages that will report domain specific details for disallowed features, but it already prohibits them.
+## See Also ##
+ * [dotty#1900](https://github.com/lampepfl/dotty/pull/1900) is implementation for Dotty