Skip to content

Latest commit

 

History

History
137 lines (109 loc) · 5.54 KB

HACKING.md

File metadata and controls

137 lines (109 loc) · 5.54 KB
Raw

Guidelines for developing OASIS

Updates in the file _oasis for the project OASIS itself

_oasis and setup.ml of the OASIS project need to be updated with the previously released version of OASIS or the very same version being released.

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 setup.ml 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).

Creating plugins

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-hello is provided by the plugin print-hello. Example
  • oasis plugins (oasis): they are used in _oasis: these plugins help to process the content of an _oasis file 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 options -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.
  • Change version in _oasis, drop the ~HEAD, rerun oasis setup and commit.
  • make deploy
  • 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 expressed in _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.
  • 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.

Backwards compatibility

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.

For example:

  • Debian stable is released with OASIS 0.2.0
  • We will continue to support OASISFormat: 0.1 as long as possible but, at some point we will enforce using at least OASISFormat: 0.2.

A list of supported OASISFormat can be found in OASISPackage_intern.ml.

Debian relationship

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.