unikernel/duniverse/dune_/doc/goals.rst

@@ -0,0 +1,149 @@
+************
+Goal of Dune
+************
+
+.. TODO(diataxis)
+   This is an important page and should go in a sort of meta section together
+   with the history of the project and the glossary for example.
+
+The Dune project strives to provide the best possible build tool for the entire
+OCaml community, including individual developers contributing to open source
+projects in their free time, larger companies (such as Jane Street), and
+communities, like MirageOS and Irmin. Additionally, we aim to provide the same
+features for other neighbouring communities, such as Coq and possibly
+Reason/Bucklescript, in the future.
+
+We haven't reached this goal yet, as Dune still requires development in some
+areas to be such a tool, but we're steadily working towards that goal. On a
+practical level, a few boxes must be checked, and a considerable number of
+details needs to be sorted out. At a high-level, we think a tool that works for
+everyone in the OCaml community should at least:
+
+1. have excellent backward compatibility properties
+2. have a robust and scalable core
+3. remain a no-brainer dependency
+4. remain accessible
+5. have very good support for the OCaml language
+6. be extensible
+
+At this point, we've done a good job at 1, 3, 4, and 5. We're currently working
+towards 2 and are doing the preparatory work for 6. Once all these boxes have
+been checked, we'll consider the Dune project complete.
+
+Below, we develop each point and give some
+insights into our current and future focuses.
+
+Have Excellent Backward-Compatibility Properties
+================================================
+
+In an open source community, two types of groups exist: those with enough
+resources to continuously bring their projects up-to-date and those who work on
+them in their free time. The latter obviously can't provide the same level of
+continuous support and updates as the former.
+
+From the Dune point of view, we consider every released project with ``dune``
+files a precious piece that will potentially never change, so we discourage
+changing Dune in a way where it could no longer understand a released project.
+
+Of course, we can't give a 100% guarantee that Dune will always behave exactly
+the same. That would be unrealistic and would prevent the project from moving
+forward. In order to provide good backward-compatibility properties while still
+keeping the project fresh and dynamic, we need to properly delimit, document,
+and version the set of behaviours on which users rely. For this to be
+manageable, the surface Dune API must remain small.
+
+A distinguishing feature of Dune allows the user to declare which version of
+the ``dune`` tool they wrote the project against, and ``dune`` will morph
+itself to behave the same as this version of the ``dune`` binary, even if it's
+a newer version. As a result, a recent ``dune`` binary version can understand a
+wide range of Dune projects written against many different versions of Dune,
+and while we strictly follow `semantic versioning`_, new major versions of Dune
+effectively introduce very few breaking changes. Most projects don't need upper
+bounds on Dune.
+
+This guarantee is of course limited to documented behaviours.
+
+.. _semantic versioning: https://semver.org/
+
+Have a Robust and Scalable Core
+===============================
+
+Tech companies tend be fond of big mono repositories, so for compatibility,
+Dune must consume large repositories without blinking. It not only needs to
+build fast, but more importantly, it must not impede fast feedback during
+development, no matter the size of the repository.
+
+Note that we'll only test Dune on repositories as large as people participating
+in Dune's development require. Currently, the largest user is Jane Street. If
+someone wanted to use Dune on much larger repositories than the ones used at
+Jane Street, and this required a significant amount of effort on Dune, this
+wouldn't be considered unless we get some help to do so and we can keep the
+other promises.
+
+In particular, while making Dune scalable, we must also ensure Dune doesn't
+turn into a monster, because no one wants to force their users to install a
+monster to build their project. This brings us to the next point of Dune being
+a no-brainer dependency:
+
+Remain a No-Brainer Dependency
+==============================
+
+Dune is a hard dependency of any Dune project. Anyone using Dune to develop
+their project will have to ask their user to install Dune. For this reason, it
+is very important to keep Dune as lean as possible.
+
+We need to be careful when we start relying on an external piece of software or
+when we introduce new concepts. We must not introduce duplication or useless
+stuff. The overall projects has to remain lean.
+
+It's also important to keep Dune as easy to install as possible. Currently, the
+only requirement to build Dune is a working OCaml compiler. Nothing else is
+required, not even a shell, and we should keep it this way.
+
+Remain Accessible
+=================
+
+Since Dune aims to be the best possible tool for the whole OCaml community,
+it's important to keep Dune accessible. Getting started and learning Dune
+should be straightforward.
+
+For that purpose, when designing the language (the command line interface or
+the documentation), we must take on the new-user perspective, one who just
+discovered Dune and its features, because Dune should be suitable for everyone!
+It also needs to provide advanced and more complex features for expert users.
+However, the documentation should always flow from the simpler concepts and
+common tasks to the more complex ones, even if the simpler features can be
+explained as instances of the more general ones.
+
+Have Excellent Support for the OCaml Language
+=============================================
+
+There are many, many build systems out there. Dune stands out because it
+primarily targets the OCaml community, so Dune must come with excellent support
+for the OCaml language and OCaml projects in general.
+
+If it didn't, Dune would just be yet another generic build system.
+
+Perhaps in the future some of the general build system will take over, and Dune
+might just become a plugin in this system. It could even disappear into the
+language, if the compiler gains significant high-level features. But for now,
+Dune is a standalone build system that primarily serves the OCaml community's
+needs, and to the extent that is reasonably possible, the needs of other
+functional language communities.
+
+Be Extensible
+=============
+
+No matter the quality of the OCaml language's support, it will never be enough
+to cover every single project need. For this reason, Dune must provide some
+form of openness for projects with need that don't completely fit in the Dune
+model.
+
+In the long run, extensibility tends to obstruct innovation, and we should
+always strive to ensure that we cover all the general needs of the main Dune
+language; however, we'll always need an escape hatch for Dune to remain a
+practical choice.
+
+It's pretty clear that extensibility must be done via OCaml code, and currently
+it's a bit difficult to use OCaml as a proper extension language, though some
+work is being done to help on that front.