Semantic versioning; safely breaking Lwt (proposal) #293

Closed
aantron opened this Issue Nov 21, 2016 · 1 comment

Comments

Projects
None yet
1 participant
@aantron
Collaborator

aantron commented Nov 21, 2016

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. #230, #269, #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

This comment has been minimized.

Show comment
Hide comment
@aantron

aantron Apr 19, 2017

Collaborator

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

Collaborator

aantron commented Apr 19, 2017

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

@aantron aantron closed this Apr 19, 2017

aantron added a commit that referenced this issue Jun 8, 2017

Port to jbuilder
This also ports the PPX to ocaml-migrate-parsetree.

The work in this commit, and the preceding one, was done by Andrew Ray
(@andrewray) in #374. These two commits are just a more blame-friendly
version; the detailed history is visible #374.

Some number of follow-on commits will probably be needed to fully
stabilize and finalize the port. Also, this commit breaks some packages
that depend on Lwt incorrectly. We will probably take steps to break
them more softly than is being done by this commit alone.

Builds on 4.05 are temporarily disabled, due to jbuilder not working
with the 4.05 betas. We will address this by building on trunk later.

This port disables coverage via Bisect completely (#319). We will
restore that in follow-on work; in the meantime, we expect few enough
edits to the test suite to be made that we can run the test suite with
coverage in a separate branch that does not yet have this commit, and
cherry-pick commits over if any development of the test suite occurs.

The build system produced by this commit is a bit of a chimera: it
adopts jbuilder without adopting modern packaging best practices. We
need to do the latter slowly, to avoid breaking projects that depend on
Lwt without proper warning (#293). Work along this direction had already
started (#301, #338, #370), and this jbuilder port will make it easier
to continue.

The port also pre-emptively solves a lot of other issues with the build
system. See the pull request for any issue links, to be added over the
coming days.

Maintainer's note: squash and summary done by Anton Bachin (@aantron).

@aantron aantron referenced this issue Jun 8, 2017

Closed

Port to jbuilder #374

aantron added a commit that referenced this issue Jun 8, 2017

Port to jbuilder
This also ports the PPX to ocaml-migrate-parsetree.

The work in this commit, and the preceding one, was done by Andrew Ray
(@andrewray) in #374. These two commits are just a more blame-friendly
version; the detailed history is visible #374.

Some number of follow-on commits will probably be needed to fully
stabilize and finalize the port. Also, this commit breaks some packages
that depend on Lwt incorrectly. We will probably take steps to break
them more softly than is being done by this commit alone.

Builds on 4.05 are temporarily disabled, due to jbuilder not working
with the 4.05 betas. We will address this by building on trunk later.

This port disables coverage via Bisect completely (#319). We will
restore that in follow-on work; in the meantime, we expect few enough
edits to the test suite to be made that we can run the test suite with
coverage in a separate branch that does not yet have this commit, and
cherry-pick commits over if any development of the test suite occurs.

The build system produced by this commit is a bit of a chimera: it
adopts jbuilder without adopting modern packaging best practices. We
need to do the latter slowly, to avoid breaking projects that depend on
Lwt without proper warning (#293). Work along this direction had already
started (#301, #338, #370), and this jbuilder port will make it easier
to continue.

The port also pre-emptively solves a lot of other issues with the build
system. See the pull request for any issue links, to be added over the
coming days.

Maintainer's note: squash and summary done by Anton Bachin (@aantron).

aantron added a commit that referenced this issue Jun 8, 2017

Port to jbuilder
This also ports the PPX to ocaml-migrate-parsetree.

The work in this commit, and the preceding one, was done by Andrew Ray
(@andrewray) in #374. These two commits are just a more blame-friendly
version; the detailed history is visible #374.

Some number of follow-on commits will probably be needed to fully
stabilize and finalize the port. Also, this commit breaks some packages
that depend on Lwt incorrectly. We will probably take steps to break
them more softly than is being done by this commit alone.

Builds on 4.05 are temporarily disabled, due to jbuilder not working
with the 4.05 betas. We will address this by building on trunk later.

This port disables coverage via Bisect completely (#319). We will
restore that in follow-on work; in the meantime, we expect few enough
edits to the test suite to be made that we can run the test suite with
coverage in a separate branch that does not yet have this commit, and
cherry-pick commits over if any development of the test suite occurs.

The build system produced by this commit is a bit of a chimera: it
adopts jbuilder without adopting modern packaging best practices. We
need to do the latter slowly, to avoid breaking projects that depend on
Lwt without proper warning (#293). Work along this direction had already
started (#301, #338, #370), and this jbuilder port will make it easier
to continue.

The port also pre-emptively solves a lot of other issues with the build
system. See the pull request for any issue links, to be added over the
coming days.

Maintainer's note: squash and summary done by Anton Bachin (@aantron).

aantron added a commit that referenced this issue Jun 8, 2017

Port to jbuilder
This also ports the PPX to ocaml-migrate-parsetree.

The work in this commit, and the preceding one, was done by Andrew Ray
(@andrewray) in #374. These two commits are just a more blame-friendly
version; the detailed history is visible #374.

Some number of follow-on commits will probably be needed to fully
stabilize and finalize the port. Also, this commit breaks some packages
that depend on Lwt incorrectly. We will probably take steps to break
them more softly than is being done by this commit alone.

Builds on 4.05 are temporarily disabled, due to jbuilder not working
with the 4.05 betas. We will address this by building on trunk later.

This port disables coverage via Bisect completely (#319). We will
restore that in follow-on work; in the meantime, we expect few enough
edits to the test suite to be made that we can run the test suite with
coverage in a separate branch that does not yet have this commit, and
cherry-pick commits over if any development of the test suite occurs.

The build system produced by this commit is a bit of a chimera: it
adopts jbuilder without adopting modern packaging best practices. We
need to do the latter slowly, to avoid breaking projects that depend on
Lwt without proper warning (#293). Work along this direction had already
started (#301, #338, #370), and this jbuilder port will make it easier
to continue.

The port also pre-emptively solves a lot of other issues with the build
system. See the pull request for any issue links, to be added over the
coming days.

Maintainer's note: squash and summary done by Anton Bachin (@aantron).

@aantron aantron referenced this issue in ocaml/ocaml Jul 13, 2017

Closed

Avoid "internal" deprecation warnings #1237

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment