How do the version numbers of release relate to stability of the API. I guess I really mean public methods on public classes, for example if I write code against 1.1.0, should I expect it to compile and work as expected against 1.2.0? or 2.0 when it comes? Is there a deprecation policy, how long (generally speaking) would a method or class be marked deprecated before it is removed? Do you record a list of changes to public classes & methods in the release notes, between major or minor versions?
For public methods, particularly interfaces and classes tagged with @PublicAPI or @PublicSPI, we will try not to break compatibility. Generally deprecated methods and classes are supported long term wherever possible, but may disappear after a release or two if there have been major changes internally that make continued support inadvisable. Going forward we’ll be taking the approach that minor versions will be API compatible between releases and major versions may break some API contracts, although usually this will only be to provide considerable extra functionality and we’ll help with the transition between APIs both from a data and an API perspective.
We don’t currently record a list of changes to public classes and methods but I’ll bear that in mind for the next release.