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

feat: Relax the client/server coupling & Add support for API versioning #426

Merged
merged 2 commits into from
Sep 29, 2021

Conversation

erikmd
Copy link
Member

@erikmd erikmd commented Sep 29, 2021

Excerpt of the learnocaml_api.mli file:

(** Note about backward-compatibility:

The architecture of learn-ocaml merges the (client, server) components
in the same codebase, so it's easier to update both of them in one go.

But this tight coupling meant that a learn-ocaml-client version would
only be compatible with a single server version, hence a frequent but
annoying error "API version mismatch: client v._ and server v._".

So since learn-ocaml 0.13, a given client_version will try to be
compatible with as much server_version's as possible (>= 0.12 &
<= client_version).

To this aim, each [request] constructor is annotated with a version
constraint of type [Compat.t], see [supported_versions].

Regarding the inevitable extensions of the API:

- make sure one only adds constructors to this [request] type,
- and that their semantics does not change
  (or at least in a backward-compatible way;
   see PR https://github.com/ocaml-sf/learn-ocaml/pull/397
   for a counter-example)
- but if a given entrypoint would need to be removed,
  rather add a Compat.Upto (*<*) constraint.
 *)

To sum up this PR in a few items:

  • It bumps the version to 0.13.0 (semver), instead of not 0.13 which seems not release-please compliant;
  • (and for each upcoming release, a good practice could be to bump the version (say, the patchlevel part) after tagging the release?)
  • The learn-ocaml/learn-ocaml-client API didn't changed from 0.12
  • but the salient change is that learn-ocaml-client 0.13 will support both learn-ocaml 0.12 and 0.13
  • and this PR adds the necessary infrastucture so that upcoming changes in the Learnocaml_api could specify supported-versions constraints, in a backward-compatible way.

* Actually, for upcoming releases, a good practice could be to bump
  the version (say, the patchlevel part) after tagging the release.
@erikmd erikmd added the kind: feature New user-facing feature. label Sep 29, 2021
@erikmd erikmd requested a review from yurug September 29, 2021 12:21
@erikmd
Copy link
Member Author

erikmd commented Sep 29, 2021

Note: a simple test with 0.12 could be added to actually check the cross-version compatibility.

But I guess this can be done in an upcoming GHA-dedicated PR, that would derive from what we implemented with @LouisAyroles in the learn-ocaml.el CI.

@yurug yurug merged commit 3113861 into ocaml-sf:master Sep 29, 2021
@erikmd erikmd deleted the version-api branch September 29, 2021 13:07
erikmd added a commit to pfitaxel/learn-ocaml that referenced this pull request Oct 3, 2021
…ng (ocaml-sf#426)

* chore: Bump release number to 0.13.0 (not 0.13)

* Actually, for upcoming releases, a good practice could be to bump
  the version (say, the patchlevel part) after tagging the release.

* feat: Add declarative Learnocaml_api.request versioning

* BREAKING-CHANGE: to be reverted: Remove learn-ocaml-client.opam.locked
erikmd added a commit to pfitaxel/learn-ocaml.el that referenced this pull request Oct 3, 2021
* learn-ocaml.el (learn-ocaml-since-upto, learn-ocaml-compat):
  Add elisp counterpart of Learnocaml_api.Compat,
  <ocaml-sf/learn-ocaml#426>

  (learn-ocaml-client-server-min-version):
  Add/Use learn-ocaml-client-server-min-version-compat.

  (learn-ocaml-on-load):
  Add/Use learn-ocaml-feature-passwd-compat.

* 001-common/runtests.el (a14_learn-ocaml-compat): Add tests
erikmd added a commit to pfitaxel/learn-ocaml.el that referenced this pull request Oct 3, 2021
* learn-ocaml.el (learn-ocaml-since-upto, learn-ocaml-compat):
  Add elisp counterpart of Learnocaml_api.Compat,
  <ocaml-sf/learn-ocaml#426>

  (learn-ocaml-client-server-min-version):
  Add/Use learn-ocaml-client-server-min-version-compat.

  (learn-ocaml-on-load):
  Add/Use learn-ocaml-feature-passwd-compat.

* 001-common/runtests.el (a14_learn-ocaml-compat): Add tests
@erikmd erikmd added this to the learn-ocaml 0.13.0 milestone Nov 2, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
kind: feature New user-facing feature.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants