Skip to content

Instantly share code, notes, and snippets.

@dbuenzli

dbuenzli/ocaml-deprecate.md

Last active November 11, 2019 12:00
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save dbuenzli/76ed925c76cc1d13d379a2d5543e112e to your computer and use it in GitHub Desktop.
Save dbuenzli/76ed925c76cc1d13d379a2d5543e112e to your computer and use it in GitHub Desktop.
Download ZIP
Deprecation procedure for OCaml
Raw
ocaml-deprecate.md

Deprecation procedure for OCaml

In order to deprecate a feature from the OCaml system the following steps are taken:

  1. Introduce a workaround for the deprecation (if needed). Document the workaround, see below.
  2. When Debian stable has the version in which the workaround was introduced, start deprecating the feature with a visible warning message.
  3. n versions after point 2. occured, remove the feature. n may vary according to the feature and may be ∞, but a resonable baseline is 4 (i.e. two years assuming two OCaml releases per year).

To keep track of deprecations a DEPRECATION.adoc file (or a dedicated section of the manual) is added to the source repository which has the following table:

feature   workaround   deprecated   removal (planned)   gone
----------------------------------------------------------------
name      vX (#PR)     vY (#PR)     vZ                  vW (#PR)

The person introducing the workaround for the deprecated feature must add a line in that document that indicates the version in the workaround column. If there is no workaround the deprecated and removal (planned) columns can be filled directly.

In the preparation of a new compiler release vR the release manager is responsible for consulting the table and:

  1. For each line of the table for which the workaround column is lower or equal to the current version of OCaml in Debian stable, introduce a deprecation warning and add version vR in the deprecated column and vR+n in the removal (planned) column.
  2. For each line of the table for which the removal (planned) column matches vR, make a PR to remove the feature and update the gone column.

Comments

  1. This procedure is relevant for the current state of compiler tooling assuming code bases that need to compile on a reasonable range of compiler versions -- here with the lowest bound being determined by the version of OCaml in Debian stable. It avoids having developers to have to live with warning without being able to act on it or to have them silent it (which defeats the purpose of having a deprecation procedure).
  2. Debian is chosen as the lower bound because it is good for installing applications if you don't care about the underlying technology. I'm myself a volunteer sysadmin for an organization and I'm glad I can handle all the php infrastructure for their applications without having to worry (too much :-) about it. For this reason I personally consider the compiler version on Debian stable as being the current, relevant OCaml compiler version, YMMV and this is of course highly debatable.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment