Guidelines for developing OASIS
Updates in the file
_oasis for the project OASIS itself
setup.ml of the OASIS project need to be updated with the
previously released version of OASIS or the very same version being
You should never use the version of OASIS under development to update the setup.ml of the project
The reason for that decision is that if you generate a new version of
using the version under development, each commit will include a change in
setup.ml and it will be mostly a repetition of something you wrote elsewhere
in your commit. Moreover, it can lead to conflict and it is never good to have
to worry about conflicts (it has generated irreconcilable changes when the
project was using darcs).
There are two kind of plugin:
- oasis command line plugins (oasis-cli): they create subcommand for the
command line interface of
oasis. For example, the subcommand
oasis print-hellois provided by the plugin
- oasis plugins (oasis): they are used in
_oasis: these plugins help to process the content of an
_oasisfile and generates additional content in the target package. Example, Example usage
oasis's plugin system uses findlib to detect plugins, so you must install
plugins as a standard OCaml library with a META file. OASIS detects plugins when
they have a field
plugin_system = "oasis" or
plugin_system = "oasis-cli" in
their META file.
Plugins are loaded as needed. You can ignore plugins with the command line
-ignore-plugins. 'oasis' plugins are loaded if they appears in a
plugin field of an
_oasis file. 'oasis-cli' plugins iare loaded when you
invoke their name on the command line.
Cut a release
- Check status on Jenkins(1, 2), Travis and AppVeyor.
- Run headache.
- Update CHANGES.txt:
- git log 0.4.2..HEAD >> CHANGES.txt
- Date, first entry must be "Version X.Y.Z".
- Major/Minor changes.
- Features section.
- Thanks section.
- Create a blog post.
- See the blog post example for content
- Change version in
_oasis, drop the ~HEAD, rerun
oasis setupand commit.
- Make sure the new version is X.Y.Z~HEAD and maybe rerun update.
- Update Change Log in the Files section of forge:
- Copy-paste last entry of CHANGES.txt, not including the first line (date...).
- Don''t Merge lines of para.
- Check 'Preserve my pre-formatted text.'
- Check the result.
- Add new version to trackers (Bugs/Pull request).
- Publish an OPAM package.
- Close all bugs in the CHANGES.txt on trackers (1).
- Publish blog post with updated download links.
- G+ announce as OASIS.
- Reshare G+ post on OCaml community.
- Send mail to caml-list, oasis-devel.
Versions support policy
To help keep OASIS as widely usable as possible, we should be conservative about the minimum required version of our dependencies. Here are some policies, to determine what version of a dependency we should require:
- For generated setup.ml:
- No deps (standalone) except OCaml
- OCaml version must be at least the one in Debian stable.
- For generated files (e.g. myocamlbuild.ml):
- Version of the target in Debian stable or that matches the constraint
_oasis. E.g. if OCamlVersion: >= 4.01, we can generate myocamlbuild.ml for this specific version because the constraint will be checked at configure time.
- Version of the target in Debian stable or that matches the constraint expressed in
- For the OASIS sources:
- OCaml version in Debian stable.
- All deps must be in Debian stable.
- Exception for related projects: ocamlmod, ocamlify, ocaml-data-notation
- For the OASIS tests:
- Version published, no strong requirement since tests can be disabled.
OASIS supports the former version of OASISFormat. Most of the important things have been backported to former version. However in the long term we might decide to drop support of old OASISFormat.
We will support a version of OASISFormat for as long as possible. However, we may drop support for any OASISFormat version older than the version of OASIS in Debian stable.
- Debian stable is released with OASIS
- We will continue to support OASISFormat:
0.1as long as possible but, at some point we will enforce using at least OASISFormat:
A list of supported OASISFormat can be found in OASISPackage_intern.ml.
We often use Debian, especially for version reference. OCaml support in Debian has a long history and we need to pick one reference. Since one of the upstream author is related to Debian, we made the decision to synchronize on Debian stable release.