Document compatibility guarantees

[jrudolph]

Initial thinking:

• be not as strict as akka proper
• try to keep binary compatibility
  • not keeping it would somewhat discourage building third-party extensions which would be hard to use if we don't keep our API binary compatible
• but try to be pragmatic about it
  • we've got some traits/interfaces that are kept non-final for code organization reasons but that evolve in a way that custom implementations would break -> collect all those traits (all model things, Directives and XYZDirectives) and discourage from extending
  • binary compatibility may be trade-off
  • e.g. recent Multipart change which is a binary-compatibility breaking change which was somewhat unlikely to be noticed
• introduce @experimental documentation or annotation marker that marks API that is not yet stable (#438)
  • we should also set some guidelines how to handle methods created like this
  • Does @experimental API need to be promoted after a fixed period of time?
  • What would be the reasons to get rid of @experimental API?
    • hard to maintain
    • bugs / generally unsupported
• define deprecation cycles for stable APIs to be phased out

[patriknw]

try to keep binary compatibility not keeping it would somewhat discourage building third-party extensions which would be hard to use if we don't keep our API binary compatible

How many such extensions libraries are there, how many do we expect? 10, 100, 1000?

Wouldn't it be reasonable that such libraries release a new version when we release a new major version as long as we don't do it too often? If binary incompatible changes are collected and done all at the same time (bumbing the major version) for example twice per year?