Add a migration file (#781)

MIGRATION.md

@@ -0,0 +1,116 @@
+Migrating from Jbuilder to Dune
+===============================
+
+Dune was initially called Jbuilder. Up to mid-2018, the package was
+still called `jbuilder` which only installed a `jbuilder` binary. This
+document explain how the migration to Dune will happen.
+
+Timeline
+--------
+
+The general idea is that the migration is gradual and existing
+Jbuilder projects don't need to be updated all at once. We encourage
+users to switch their development repositories and continue their
+usual release cycle. There is no need to re-release existing packages
+just to switch to Dune immediately.
+
+The plan is as follow:
+
+### July 2018: release of Dune 1.0.0
+
+First release of the opam package `dune`. The `jbuilder` package
+becomes a transitional package that depends on `dune`.
+
+The `dune` package installs two binaries: `dune` and `jbuilder`. These
+two binaries are exactly the same and they work on both Jbuilder and
+Dune projects. Additionally they recognize both Jbuilder and Dune
+configuration files. The new Dune configuration files are described
+later in this document.
+
+### January 2019: deprecation of Jbuilder
+
+At this point, the `jbuilder` binary emits a warning on every startup
+inviting users to switch to `dune`. When encountering `jbuild` or
+other Jbuilder configuration files, both binaries emit a warning. The
+rest is unchanged.
+
+During this period, it makes sense for projects to do new releases
+just to switch to Dune if none of their existing releases is using
+Dune.
+
+### July 2019: support for Jbuilder is dropped
+
+`jbuilder` is now a dummy executable that always exit with an error
+message on startup. `dune` no longer reads `jbuild` or other Jbuidler
+configuration files but still prints a warning when encountering
+them.
+
+At this point, a conflict with newer versions of `dune` will be added
+to all opam packages that rely on the `jbuilder` binary or Jbuilder
+configuration files.
+
+### January 2020: the jbuilder binary goes away
+
+The `dune` package no longer installs a `jbuilder` binary. The rest is
+unchanged.
+
+### Distant future
+
+Once we are sure there are no more `jbuild` files out there, Dune will
+completely ignore `jbuild` and other Jbuilder configuration files.
+
+New configuration files
+-----------------------
+
+Until July 2019, `dune` will still read `jbuild` and other Jbuilder
+configuration files. There is no change in these files.
+
+However, based on the experience acquired since the first release of
+Jbuilder, we made a few changes in the configuration files read by
+Dune. The most notable ones are the following:
+
+- `jbuild` files are renamed simply `dune`
+- projects now have a `dune-project` file at their root
+- `jbuild-ignore` files are replaced by `ignored_subdirs` stanzas in
+  `dune` files
+- `jbuild-workspace` are replaced by `dune-workspace` files
+- `jbuild-workspace<suffix>` files no longer mean anything
+
+Following are detailed explanation of the differences between the
+Jbuilder configuration files and the Dune ones.
+
+### dune-project files
+
+These are a new kind of file. With Jbuilder, projects used to be
+identified by the presence of at least one `<package>.opam` file in a
+directory. This will still be supported until July 2019, however as
+Jbuilder evolved it became clear that we needed project files, so Dune
+introduces `dune-project` files to mark the root of projects.
+
+Eventually, we are hoping that Dune will generate opam files. So users
+will only have to write a `dune-project` file.
+
+The purpose of this file is to:
+- delimit projects in larger workspaces
+- set a few project-wide parameters, such as the name, the version of
+  the Dune language in use or specification of extra features
+  (plugins) used in the project
+
+Eventually, for users who wish to do so it should be possible to
+centralize all the configuration of a project in this file.
+
+### dune files
+
+These are the same as `jbuild` files.
+
+### dune-workspace
+
+These are the same as `jbuild-workspace` files.
+
+When looking for the root of the workspace, Jbuilder also looks for
+files whose name start with `jbuild-workspace`, such as
+`jbuild-workspace.in`. This rule will be kept until July 2019, however
+it is not preserved for `dune-workspace` files. I.e. a
+`dune-workspace.in` file means nothing.
+
+This rule was only useful when we didn't have project files.