[buildstream] 01/01: Mission statement in the readme

[ro...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

root pushed a commit to branch tristan/mission-statement
in repository https://gitbox.apache.org/repos/asf/buildstream.git

commit 04ee0be53f4b99d563839c886febaf6607d5e325
Author: Tristan Van Berkom <tr...@codethink.co.uk>
AuthorDate: Fri Oct 19 14:51:13 2018 +0100

    Mission statement in the readme
---
 README.rst | 141 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 141 insertions(+)

diff --git a/README.rst b/README.rst
index 9a67dd4..bb2dc20 100644
--- a/README.rst
+++ b/README.rst
@@ -61,6 +61,147 @@ BuildStream offers the following advantages:
   a range of ISAs including x86_32, x86_64, ARMv7, ARMv8, MIPS.
 
 
+
+
+
+
+
+
+
+
+
+
+
+Mission statement
+=================
+
+* **Deterministic build environment**
+
+  Ideally, the build result (or *artifact*) of any given build will always be
+  bit-for-bit identical if it is given exactly the same inputs, regardless of
+  the host environment, so long as BuildStream supports the given host.
+
+  To this end, we go to some lengths to ensure a clean execution environment
+  for building, and we bump the core cache key version if ever we change or
+  improve sanitizing of the execution environment, so that everything needs
+  to be rebuilt.
+
+  While BuildStream cannot itself guarantee a bit-for-bit identical result
+  for every identical input, we can help in the majority of the work needed
+  to ensure your builds are determinstic and reproducible.
+
+* **Reusable build instructions**
+
+  Our declarative format is designed with the intention that the same BuildStream
+  project can be used to accomplish various things for the set of software it
+  defines the integration for.
+
+  For instance, using project options; it should be possible to reuse the same
+  project to deploy the same software stack, or bundle, in various ways and
+  on various platforms. This should be possible with BuildStream using only some
+  conditional statements, with minimal redundance and maximum reuse.
+
+* **Backwards compatibility**
+
+  BuildStream provides various backwards compatible stable API surfaces, in this
+  way we ensure that nobody's project can ever break as a result of upgrading to
+  a new version of BuildStream.
+
+  These stable API surfaces include:
+
+  * The command line interface. BuildStream is intended to be scriptable and integratable
+    into third party tooling. For this reason the command line interface may be extended
+    from version to version but existing interfaces cannot be modified or removed.
+
+  * The Python plugin facing API surface. In order to avoid breaking anyone's project
+    who uses a custom or third party plugin, the plugin interfaces may be extended but
+    can never be modified or removed.
+
+  * The YAML format. As the main API surface for project authors, interfaces can be
+    extended in the YAML format but never modified or removed.
+
+  Beyond stability of the API surfaces, there is also the stability of the cache
+  keys. Currently BuildStream guarantees that artifact cache keys will never change
+  in a given stable release of BuildStream (e.g., all versions of 1.2.x will produce
+  the same cache key for the same project).
+
+  It is a long term goal to also make artifact cache keys stable, that any later version
+  of BuildStream produces the same cache key for an artifact which was built by any other
+  version of BuildStream
+
+* **Build avoidance**
+
+  It is a general goal to reduce builds as much as possible. Whenever we can
+  guarantee that we already have a cached artifact which has identical inputs,
+  we should always prefer the existing artifact.
+
+* **Convenient developer experience**
+
+  As an integration tool, we place focus on determinism first, but recognize that
+  developers need to have the same guarantees of determinism as integrators do, but
+  normally lack the tooling perform edit, compile and test cycles inside a well
+  defined deterministic build environment.
+
+  BuildStream aims to bring the deterministic and predictable target system
+  environment to the developer's fingertips, while also bringing convinent
+  developer tools to the integrator.
+
+* **Decoupling of tooling and payload**
+
+  BuildStream is a generic build and integration tool which does not make any
+  assumptions about which software platform or machine architecture is going to
+  be used.
+
+  Some plugin elements invoking platform specific tooling such as autotools or
+  cmake, these provide configurable defaults for and are designed with maximum
+  configurability in mind, while the core application should not become biased
+  towards specific platforms.
+
+* **Project Modularity**
+
+  From various experiences with tooling used to produce customized Linux based
+  appliances, we have recognized a trend that is to combine all build metadata
+  for the whole stack (from kernel to the user facing applications) in a single
+  repository, we see this as problematic as it does not allow inter-organizational
+  knowledge sharing easily, or separation of teams which produce and maintain separate
+  parts of the operating system stack.
+
+  BuildStream aims to make it easier to produce and maintain systems in a modular
+  fashion, where organizations or teams can maintain and share parts of the stack.
+
+* **Easy to use**
+
+  Part of the mission is to be well documented, and as simple and straightforward
+  to use as possible.
+
+  As a part of this, we place great emphasis on error reporting, and try to fail
+  as early as possible when we know that we can fail; and provide as much useful
+  context to the user as possible to allow them to easily figure out what went
+  wrong.
+
+* **Core simplicity, maximum flexibility**
+
+  BuildStream aims to be a generic core which simply processes an abstract pipeline
+  of elements which perform filesystem permutations inside a sandboxed environment.
+
+  We address the problem of scope creep in the following ways:
+
+  - **Many simple tools exposed in the CLI**
+
+    The command line interface is composed mostly of simple commands which
+    are API stable.
+
+    In this way we allow more complex and user specific constructs to be implemented
+    as shell scripts which invoke BuildStream one or more times, instead of growing
+    user specific features directly in the BuildStream CLI.
+
+  - **Stable Plugin API**
+
+    By providing a stable plugin API with strong guarantees that BuildStream will
+    not break external plugins, we hope to encourage and develop a healthy ecosystem
+    of useful plugins which users can reliably use in their project.
+
+
 How do I use BuildStream?
 =========================
 Please refer to the `documentation <https://buildstream.gitlab.io/buildstream/>`_