Semantic versioning; safely breaking Lwt (proposal)

[aantron]

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).

[aantron]

I guess this can be closed, now that 3.0.0 is out, and this process is put in practice (though it is not yet complete, as Lwt may have to still support users that missed the breakage window).