Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Semantic versioning; safely breaking Lwt (proposal) #293

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

Semantic versioning; safely breaking Lwt (proposal) #293

aantron opened this issue Nov 21, 2016 · 1 comment
Labels

Comments

@aantron
Copy link
Collaborator

@aantron 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
Copy link
Collaborator Author

@aantron 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
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
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
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
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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
1 participant
You can’t perform that action at this time.