I suggest:

• After 2.7.0, Lwt will follow semantic versioning. Any breaking changes will bump the major version number. I expect this will happen twice per year at most. The actual changes will typically be minor (e.g. Lwt_unix.bind should be in the monad #230, Add support for selecting the libev backend #269, Replace establish_server by establish_server_safe #260). They will be batched.

How breaking changes will be done:

• An API that is being changed will be versioned. So, if Lwt_unix.foo is to be changed, there will be Lwt_unix.Versioned.foo_1 and Lwt_unix.Versioned.foo_2. A detailed deprecation annotation on foo will say:

  • If you don't wish to risk refactoring your code, use foo_1 – an alias for the current foo.
  • To get the new functionality immediately, use foo_2.

• This can be released right away.

• I (or other maintainer(s)) will notify the maintainers of any packages in OPAM that are using foo.

• After being released deprecated for at least, say, 3 months, foo will become an alias for foo_2 instead of foo_1, during a major release. This will be clearly noted in the change log.

• foo_1 and foo_2 will be marked deprecated, and will be guaranteed to persist in Lwt for at least, say, one more major release. After that, each will remain indefinitely, unless/until further maintenance becomes an unreasonable burden. This also applies to APIs that are deprecated but not broken (i.e. whose names are not being reused).