In order to deprecate a feature from the OCaml system the following steps are taken:
- Introduce a workaround for the deprecation (if needed). Document the workaround, see below.
- When Debian stable has the version in which the workaround was introduced, start deprecating the feature with a visible warning message.
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:
- 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 versionvR
in thedeprecated
column andvR+n
in theremoval (planned)
column. - For each line of the table for which the
removal (planned)
column matchesvR
, make a PR to remove the feature and update thegone
column.
- 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).
- 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.