Merge branch 'tiagogomes/improve-docs' into 'master'

Improve documentation

* Capitalize in the beggining of a sentence
* Capitalize document filenames
* Add missing periods
* Add more markdown formatting where appropriate.
* Add links for URLs and references to documents in the repo
* Remove unnecessary indentation
* Wrap at 80 characters

No changes in the instructions or wording were done is this commit.

See merge request !248

6 files changed, 262 insertions, 288 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5d3607b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,236 @@
+GitLab: [![build status](https://gitlab.com/baserock/ybd/badges/master/build.svg)](https://gitlab.com/baserock/ybd/commits/master)
+
+Github: [![Build Status](https://travis-ci.org/devcurmudgeon/ybd.svg?branch=master)](https://travis-ci.org/devcurmudgeon/ybd)
+
+# ybd
+
+ybd is a tool for building integrated software stacks. It does four things:
+
+- parse yaml files which describe integrated collections of software components
+- gather source code (from git repos) for a user-specified target collection
+- build the collection
+- optionally deploy the collection (if the yaml files describe where/how to
+  deploy)
+
+Currently ybd understands the semantics of yaml
+[definitions](http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/)
+from the [Baserock](http://wiki.baserock.org) project.
+
+The total codebase for ybd is only ~ 2200 lines of Python. even so ybd can
+reliably build all systems in Baserock's definitions.git, i.e. all of the FOSS
+components required for Linux appliances up to and including:
+
+- minimal Linux systems
+- self-hosting development systems
+- GENIVI Baseline and GENIVI Demo Platform systems for x86 and ARMv7
+- OpenStack appliances
+- OpenWRT appliances
+
+There are Concourse pipelines using ybd to integrate various examples at
+<concourse.baserock.org> ...
+
+[<img src="http://i.imgur.com/N193G9C.png" height="400" width="600">](http://concourse.baserock.org)
+
+ybd is a simple start-point for building, deploying, learning and experimenting
+with definitions, algorithms and functionality on Baserock projects. With a
+little work it can be used to build other software stacks too.
+
+ybd is under development. things will change :) If you're trying ybd for the
+first time please start with the latest tag, not master.
+
+ybd is designed for Linux, but can be used on other environments (eg MacOS)
+using Vagrant and VirtualBox.
+
+## Quick Start
+
+On Fedora, Ubuntu, Debian (as root... hoping to fix this for non-root soon):
+
+    git clone git://gitlab.com/baserock/ybd && cd ybd
+    # checkout latest tag
+    git checkout `git describe --tags $(git rev-list --tags --max-count=1)`
+    sudo sh ./install_dependencies.sh
+    cd .. && git clone git://git.baserock.org/baserock/baserock/definitions
+    cd definitions
+
+Or using Vagrant with VirtualBox:
+
+    git clone git://gitlab.com/baserock/ybd && cd ybd
+    # checkout latest tag
+    git checkout `git describe --tags $(git rev-list --tags --max-count=1)`
+    vagrant up
+    vagrant ssh
+    sudo -i
+    cd /src/definitions
+
+Once there you can run (as root)
+
+    ../ybd/ybd.py $1 $2
+
+where
+
+- `$1` is relative path to a chunk, stratum, system or cluster definition file
+- `$2` specifies the architecture you're building/deploying for.
+
+Note that all of the current baserock definitions are for native builds, no
+cross-compile. So if you're on a PC/Mac it may be that your only option for
+`$2` is `x86_64`.
+
+Some examples to try:
+
+    # on an x86_64 laptop running linux, to build a build-system...
+    ../ybd/ybd.py systems/build-system-x86_64.morph x86_64
+
+    # on the same laptop, to build gcc (and its dependencies)
+    ../ybd/ybd.py gcc x86_64
+
+    # on the same laptop, to build the genivi stratum (and its dependencies)
+    ../ybd/ybd.py strata/genivi.morph x86_64
+
+    # on a jetson, to build a GENIVI baseline system...
+    ../ybd/ybd.py systems/genivi-baseline-system-armv7lhf-jetson.morph armv7lhf
+
+    # on anything, to build (and deploy?) parts of baserock release...
+    ../ybd/ybd.py clusters/release.morph x86_64
+
+    # in a baserock devel vm (x86_64), to build and deploy a self-upgrade...
+    ../ybd/ybd.py clusters/upgrade-devel.morph x86_64
+
+ybd generates a lot of log output to stdout, which hopefully helps to explain
+what is happening. If you need a permanent log then try
+
+    ../ybd/ybd.py clusters/upgrade-devel.morph x86_64 | tee some-memorable-name.log
+
+More information about ybd's dependencies is in
+[dependencies](docs/Dependencies.md).
+
+
+## Configuration
+
+ybd is designed to be run from the command line and/or as part of an automated
+pipeline. all configuration is taken from conf files and/or environment
+variables, in the following order of precedence:
+
+    YBD_* environment variables         # if found
+    ./ybd.conf                          # if found
+    $path/to/ybd.py/ybd.conf            # if found
+    $path/to/ybd.py/ybd/config/ybd.conf # default, as provided in the ybd repo
+
+This means you can set custom config via env vars, or the definitions top-level
+directory, or the ybd top-level directory, without having to modify the
+supplied default [ybd.conf](ybd/config/ybd.conf).
+
+NOTE we recommend you create your own ybd.conf file. that way you can git merge
+new versions of ybd + definitions, and your custom settings will always take
+precedence, with no possibility of a merge conflict.
+
+To set config via environment variables, each must be prefixed with `YBD_`
+and using `_` instead of `-`. ybd will strip the `YBD_` prefix and
+convert `_` to `-`. For example
+
+    export YBD_artifact_version=1     # artifact-version: 1
+    export YBD_log_verbose=True       # log-verbose: True
+    export YBD_instances=2            # instances: 2
+
+ybd does not support unix-style --flags so far. If enough people complain about
+that, it can be fixed.
+
+For details about the config options themselves, see
+[ybd.conf](ybd/config/ybd.conf).
+
+## Interesting Features
+
+### Run ybd in Parallel
+
+ybd can fork several instances of itself to parallelise its work. There is no
+intelligence in the scheduling - all of the forks just randomise their
+build-order and try to build everything. For building a set of overlapping
+systems in parallel on a many core machine this proves to be quite effective.
+For example on a 36-core AWS c4.8xlarge machine, 4 racing instances of ybd can
+build all of the x86_64 systems in definitions/clusters/ci.morph much faster
+than a single instance.
+
+To try it, just set the `instances` config variable, for example
+
+    # as an environment variable...
+    export YBD_instances=4
+
+    # or in a ybd.conf file...
+    instances: 8
+
+You should probably think about setting `max-jobs` too, taking into account
+your workloads and host machine(s). If `max-jobs` is not set, ybd will default
+it to number-of-cores/instances.
+
+### kbas Cache Server
+
+kbas is a basic server which can be used to allow other users to access
+pre-built artifacts from previous or current runs of ybd. See kbas/kbas.py for
+the code. With minimal configuration it can serve artifacts to instances of ybd
+on other machines, and also receive uploaded artifacts.
+
+To launch kbas, just do
+
+    cd kbas && ./kbas.py
+
+By default ybd is configured to check for artifacts from a kbas server at
+<http://artifacts1.baserock.org:8000/>.
+
+Config for kbas follows the same approach as ybd, defaulting to config in
+`kbas/config/kbas.conf`.
+
+NOTE: the default password is 'insecure' and the uploading is disabled unless
+you change it.
+
+### Concourse Pipelines
+
+[WORK IN PROGRESS] ybd can generate concourse pipelines - see the code at
+ybd/concourse.py
+
+To start a local concourse instance:
+
+    # in your definitions directory
+    vagrant init concourse/lite
+    vagrant up
+    # generate pipeline, run concourse.py (same arguments as ybd.py)
+    python ../ybd/ybd/concourse.py <target> <arch>
+    fly -t local login -c http://192.168.100.4:8080
+    fly -t local set-pipeline -p <target> -c <target>.yml
+
+You can view the local pipelines at <http://192.168.100.4:8080>.
+
+## TODO
+
+In no particular order, here's a list of things that may be interesting to try
+doing to/with ybd:
+- pip install
+- Deterministic (bit-for-bit) build
+- Fix deployment: ybd currently can deploy systems, subsystems (test this?) and
+  upgrades, but it's a mess:
+  - can't select which subsystems to deploy (need to iron out the definitions)
+  - alter the deployment parameters (templating, or commandline?)
+  - deploy other-architecture stuff
+- Run without root privileges on non-Linux environments (eg Mac OS - needs a
+  different isolation method instead of linux-user-chroot).
+- Test assumptions by creating definitions for other OS software sets, eg
+  Aboriginal Linux and non-Linux systems.
+- Test/fix to work on old versions of definitions, and on morphs.git (and
+  separate out the idiosyncrasies, so code is tidy for future changes)
+
+## Project Guidelines
+
+- Contributions are extremely welcome - feedback, ideas, suggestions, bugs,
+  documentation will be appreciated just as much as code.
+- Key criteria for code contributions are:
+  - 'Code LESS: every line creates a work-chain. Code is a liability, not an
+    asset'
+  - think hard before adding dependencies
+  - code should be tested and pass pep8
+
+## License
+
+- License is GPLv2 but other licensing can be considered on request.
+- Most of the copyright is currently Codethink but don't let that put you off.
+  There's no intent to keep this as a Codethink-only project, nor will there be
+  any attempt to get folks to sign a contributor agreement.  contributors
+  retain their own copyright.
+
diff --git a/docs/archaeology.md b/docs/Archaeology.md
index 3aac8b1..37a363b 100644
--- a/docs/archaeology.md
+++ b/docs/Archaeology.md
@@ -1,7 +1,7 @@
 ## Archaeology
 
-One of the stated aims of Baserock has been to ensure that old systems can
-be reproduced a long time into the future (decades, for example).
+One of the stated aims of Baserock has been to ensure that old systems can be
+reproduced a long time into the future (decades, for example).
 
 Stating it doesn't make it true, though.
 
@@ -12,7 +12,9 @@ themselves; we had never specified the definitions format, after all. In the
 end it seemed more productive to fix the assumptions and move forward, rather
 than make ybd repeat the mistakes.
 
-For what it's worth, as of 2016-04-10 ybd parses all the way back to baserock-14.40, which was the first tag where the morph files were organised into subdirectories. Going back further could be attempted, if we consider it
+For what it's worth, as of 2016-04-10 ybd parses all the way back to
+baserock-14.40, which was the first tag where the morph files were organised
+into subdirectories. Going back further could be attempted, if we consider it
 worthwhile to exhume the builds further back.
 
 This is how ybd behaves on various historical versions of ci.morph:
@@ -30,4 +32,4 @@ baserock-15.17-rc:
     (VERSION: 1) crashes on pygobject
 
 baserock-15.19:
-    (VERSION: 3) builds successfully
\ No newline at end of file
+    (VERSION: 3) builds successfully
diff --git a/docs/dependencies.md b/docs/Dependencies.md
index 9001b00..134b91c 100644
--- a/docs/dependencies.md
+++ b/docs/Dependencies.md
@@ -1,12 +1,13 @@
-## dependencies
+## Dependencies
 
-ybd requires git, gcc, make, autotools, python, tar, wget. note that the Baserock definitions also require gawk.
+ybd requires git, gcc, make, autotools, python, tar, wget. Note that the
+Baserock definitions also require gawk.
 
-so for a Debian-based system:
+So for a Debian-based system:
 
     apt-get update; apt-get install build-essential gawk git m4
 
-...and a Fedora-based system:
+… and a Fedora-based system:
 
     yum install make automake gcc gcc-c++ kernel-devel git gawk m4
 
@@ -16,23 +17,19 @@ ybd also depends on [pyfilesystem](http://pyfilesystem.org),
 [requests](https://github.com/kennethreitz/requests),
 and optionally [jsonschema](https://github.com/Julian/jsonschema).
 
-to serve artifacts using kbas, it additionally requires
+To serve artifacts using kbas, it additionally requires
 [bottle](https://github.com/bottlepy/bottle) and optionally
-[cherrypy](https://github.com/cherrypy/cherrypy.git)
+[cherrypy](https://github.com/cherrypy/cherrypy.git).
 
-to use the Riemann functionality, it additionally requires
-[riemann-client](https://github.com/borntyping/python-riemann-client)
+To use the Riemann functionality, it additionally requires
+[riemann-client](https://github.com/borntyping/python-riemann-client).
 
-if you trust the Python Package Index (PyPI) and pip is available on your
+If you trust the Python Package Index (PyPI) and pip is available on your
 machine, you can install these dependencies with:
 
-```
     pip install fs pyyaml sandboxlib requests jsonschema bottle cherrypy riemann-client
-```
 
 If you need to install pip itself:
 
-```
     wget https://bootstrap.pypa.io/get-pip.py
     python get-pip.py
-```
diff --git a/docs/testing.md b/docs/Testing.md
index f78337c..dc431a5 100644
--- a/docs/testing.md
+++ b/docs/Testing.md
@@ -1,13 +1,15 @@
 check_parsing
 -------------
-YBD aims to normalise definitions into a more understandable representation.
-With the addition of 'parse-only' mode, ybd can dump this representation as
+
+ybd aims to normalise definitions into a more understandable representation.
+With the addition of _parse-only_ mode, ybd can dump this representation as
 json, and we can confirm there is no unexpected data.
 
 FIXME: identify at least one valid test-case here.
 
 check_cache_keys
 ----------------
+
 Since ybd 15.44, the cache-key algorithm appears stable and can be
 applied to definitions as far back as baserock-14.40.
 
@@ -16,7 +18,6 @@ algorithm. This doesn't matter much for the cache-key algorithm itself,
 since it is versioned, but checking that we can get to these values also
 confirms that we can still parse the old definitions files themselves.
 
-```
     baserock-14.40
     0: ci.6788f6634d42f0a42682bd2208cb123f69a157b4a50ac40108d91029558ec623
     1: ci.b9de86669ce182e60e3f9445e6394b478b67a2c73b4c0764491c158c5f2569e9
@@ -28,10 +29,10 @@ confirms that we can still parse the old definitions files themselves.
     baserock-15.47.1
     0: ci.a809e39d26fea31b2dc674e190f6367a10cedaffe644775a59a93719cc5d5290
     1: ci.ce7f81b2e294c1893a08e4b18cf1d9a74f5e49bb58f7099ab55f656a05d887b4
-```
 
 check splits
 ------------
+
 We reduce the size of systems artifacts by installing a only subset of the
 outputs from the builds during the assembly process. The code for this
 is mainly in splitting.py, and involves applying regex expressions to the
@@ -44,9 +45,8 @@ list of generated files, and compare new runs against it as a regression test.
 
 The best candidate is minimal-system, since this expressly makes use of a lot
 of splitting. The proposed test case is from Richard Dale's original commit
-of the split functionality...
+of the split functionality…
 
-```
     artifact-version: omitted
     definitions version: baserock-15.47.1
     ybd version: rdale/150-master-splitting
@@ -57,11 +57,9 @@ of the split functionality...
       result: 6c3c9ad75990b93e1927012928444b83
     find . -type f | sort | wc -l
       result: 155
-```
 
-But we should also test (say) devel-system...
+But we should also test (say) devel-system…
 
-```
     artifact-version: omitted
     definitions version: baserock-15.47.1
     ybd version: rdale/150-master-splitting
@@ -75,6 +73,4 @@ But we should also test (say) devel-system...
     find . -type f | sort | md5sum
       result: 5c6e4561557d319059986c161565f4bf
 
-```
-
-The above was achieved on AWS
\ No newline at end of file
+The above was achieved on AWS.
diff --git a/docs/releasing.md b/docs/releasing.md
index 6c553b3..ab39365 100644
--- a/docs/releasing.md
+++ b/docs/releasing.md
@@ -1,10 +1,10 @@
 # Releasing
 
-This summarises what 'releasing' means for ybd - it's a work-in-progress. 
+This summarises what _releasing_ means for ybd - it's a work-in-progress.
 
 ### Past
 
-In the first months there were no 'releases' of ybd. The early goals of the
+In the first months there were no releases of ybd. The early goals of the
 project were to parse definitions as fast as possible, then build them, then
 deploy them.
 
@@ -65,4 +65,3 @@ server time, because actual system builds are big and heavy. To improve on
 this we'd benefit from establishing a reference definition set which is
 specifically for exercising ybd/definitions/spec.
 
-
diff --git a/readme.md b/readme.md
deleted file mode 100644
index 1b518f1..0000000
--- a/readme.md
+++ /dev/null
@@ -1,256 +0,0 @@
-GitLab: [![build status](https://gitlab.com/baserock/ybd/badges/master/build.svg)](https://gitlab.com/baserock/ybd/commits/master)
-
-Github: [![Build Status](https://travis-ci.org/devcurmudgeon/ybd.svg?branch=master)](https://travis-ci.org/devcurmudgeon/ybd)
-
-# ybd
-
-ybd is a tool for building integrated software stacks. it does four things:
-
-- parse yaml files which describe integrated collections of software components
-- gather source code (from git repos) for a user-specified target collection
-- build the collection
-- optionally deploy the collection (if the yaml files describe where/how to deploy)
-
-currently ybd understands the semantics of yaml
-[definitions](http://git.baserock.org/cgi-bin/cgit.cgi/baserock/baserock/definitions.git/tree/)
-from the [Baserock](http://wiki.baserock.org) project.
-
-the total codebase for ybd is only ~ 2200 lines of Python. even so ybd can
-reliably build all systems in Baserock's definitions.git, i.e. all of the
-FOSS components required for Linux appliances up to and including:
-
-- minimal Linux systems
-- self-hosting development systems
-- GENIVI Baseline and GENIVI Demo Platform systems for x86 and ARMv7
-- OpenStack appliances
-- OpenWRT appliances
-
-there are Concourse pipelines using ybd to integrate various examples at
-concourse.baserock.org...
-
-[<img src="http://i.imgur.com/N193G9C.png" height="400" width="600">](http://concourse.baserock.org)
-
-ybd is a simple start-point for building, deploying, learning and
-experimenting with definitions, algorithms and functionality on Baserock
-projects. with a little work it can be used to build other software stacks too.
-
-ybd is under development. things will change :) If you're trying ybd for the
-first time please start with the latest tag, not master.
-
-ybd is designed for Linux, but can be used on other environments (eg
-MacOS) using Vagrant and VirtualBox.
-
-## quick start
-
-on Fedora, Ubuntu, Debian (as root... hoping to fix this for non-root soon):
-
-```
-    git clone git://gitlab.com/baserock/ybd && cd ybd
-    # checkout latest tag
-    git checkout `git describe --tags $(git rev-list --tags --max-count=1)`
-    sudo sh ./install_dependencies.sh
-    cd .. && git clone git://git.baserock.org/baserock/baserock/definitions
-    cd definitions
-```
-
-or using Vagrant with VirtualBox:
-
-```
-    git clone git://gitlab.com/baserock/ybd && cd ybd
-    # checkout latest tag
-    git checkout `git describe --tags $(git rev-list --tags --max-count=1)`
-    vagrant up
-    vagrant ssh
-    sudo -i
-    cd /src/definitions
-```
-
-once there you can run (as root)
-
-```
-    ../ybd/ybd.py $1 $2
-```
-
-where
-
-- $1 is relative path to a chunk, stratum, system or cluster definition file
-- $2 specifies the architecture you're building/deploying for.
-
-note that all of the current baserock definitions are for native builds, no
-cross-compile. so if you're on a PC/Mac it may be that your only
-option for $2 is x86_64
-
-Some examples to try:
-
-```
-   # on an x86_64 laptop running linux, to build a build-system...
-   ../ybd/ybd.py systems/build-system-x86_64.morph x86_64
-
-   # on the same laptop, to build gcc (and its dependencies)
-   ../ybd/ybd.py gcc x86_64
-
-   # on the same laptop, to build the genivi stratum (and its dependencies)
-   ../ybd/ybd.py strata/genivi.morph x86_64
-
-   # on a jetson, to build a GENIVI baseline system...
-   ../ybd/ybd.py systems/genivi-baseline-system-armv7lhf-jetson.morph armv7lhf
-
-   # on anything, to build (and deploy?) parts of baserock release...
-   ../ybd/ybd.py clusters/release.morph x86_64
-
-   # in a baserock devel vm (x86_64), to build and deploy a self-upgrade...
-   ../ybd/ybd.py clusters/upgrade-devel.morph x86_64
-```
-
-ybd generates a lot of log output to stdout, which hopefully helps
-to explain what is happening. if you need a permanent log then try
-
-```
-    ../ybd/ybd.py clusters/upgrade-devel.morph x86_64 | tee some-memorable-name.log
-```
-More information about ybd's dependencies is in docs/dependencies.md
-
-
-## configuration
-
-ybd is designed to be run from the command line and/or as part of an
-automated pipeline. all configuration is taken from conf files and/or
-environment variables, in the following order of precedence:
-
-```
-    YBD_* environment variables         # if found
-    ./ybd.conf                          # if found
-    $path/to/ybd.py/ybd.conf            # if found
-    $path/to/ybd.py/ybd/config/ybd.conf # default, as provided in the ybd repo
-```
-
-this means you can set custom config via env vars, or the definitions
-top-level directory, or the ybd top-level directory, without having to modify
-the supplied default [ybd.conf](ybd/config/ybd.conf).
-
-NOTE we recommend you create your own ybd.conf file. that way you can git
-merge new versions of ybd + definitions, and your custom settings will always
-take precedence, with no possibility of a merge conflict.
-
-to set config via environment variables, each must be prefixed with ```YBD_```
-and using ```_``` instead of ```-```. ybd will strip the YBD_ prefix and
-convert ```_``` to ```-```, for example
-
-```
-    export YBD_artifact_version=1     # artifact-version: 1
-    export YBD_log_verbose=True       # log-verbose: True
-    export YBD_instances=2            # instances: 2
-```
-
-ybd does not support unix-style --flags so far. if enough people complain about
-that, it can be fixed.
-
-For details about the config options themselves, see
-[ybd.conf](ybd/config/ybd.conf).
-
-## interesting features
-
-### run ybd in parallel
-ybd can fork several instances of itself to parallelise its work. there is no
-intelligence in the scheduling - all of the forks just randomise
-their build-order and try to build everything. for building a set of overlapping
-systems in parallel on a many core machine this proves to be quite
-effective. For example on a 36-core AWS c4.8xlarge machine, 4 racing instances
-of ybd can build all of the x86_64 systems in definitions/clusters/ci.morph
-much faster than a single instance.
-
-to try it, just set the `instances` config variable, for example
-
-```
-    # as an environment variable...
-    export YBD_instances=4
-
-    # or in a ybd.conf file...
-    instances: 8
-```
-
-you should probably think about setting `max-jobs` too, taking into account
-your workloads and host machine(s). if `max-jobs` is not set, ybd will default
-it to `number-of-cores/instances`.
-
-
-### kbas cache server
-kbas is a basic server which can be used to allow other users to access
-pre-built artifacts from previous or current runs of ybd. See kbas/kbas.py for
-the code. with minimal configuration it can serve artifacts to instances of
-ybd on other machines, and also receive uploaded artifacts.
-
-to launch kbas, just do
-
-```
-    cd kbas && ./kbas.py
-```
-
-by default ybd is configured to check for artifacts from a kbas server at
-
-```
-    http://artifacts1.baserock.org:8000/
-
-config for kbas follows the same approach as ybd, defaulting to config in
-
-    kbas/config/kbas.conf
-
-NOTE: the default password is 'insecure' and the uploading is disabled unless
-you change it.
-
-```
-
-
-### concourse pipelines
-[WORK IN PROGRESS] ybd can generate concourse pipelines - see the code at
-ybd/concourse.py
-
-to start a local concourse instance:
-```
-    # in your definitions directory
-    vagrant init concourse/lite
-    vagrant up
-    # generate pipeline, run concourse.py (same arguments as ybd.py)
-    python ../ybd/ybd/concourse.py <target> <arch>
-    fly -t local login -c http://192.168.100.4:8080
-    fly -t local set-pipeline -p <target> -c <target>.yml
-```
-
-you can view the local pipelines at http://192.168.100.4:8080
-
-## todo
-
-in no particular order, here's a list of things that may be interesting to try
-doing to/with ybd:
-- pip install
-- deterministic (bit-for-bit) build
-- fix deployment: ybd currently can deploy systems, subsystems (test this?) 
-  and upgrades, but it's a mess
-  - can't select which subsystems to deploy (need to iron out the definitions)
-  - alter the deployment parameters (templating, or commandline?)
-  - deploy other-architecture stuff
-- run without root privileges on non-Linux environments (eg Mac OS - needs a
-  different isolation method instead of linux-user-chroot)
-- test assumptions by creating definitions for other OS software sets, eg
-  Aboriginal Linux and non-Linux systems
-- test/fix to work on old versions of definitions, and on morphs.git
-  (and separate out the idiosyncrasies, so code is tidy for future changes)
-
-## project guidelines
-
-- contributions are extremely welcome - feedback, ideas, suggestions, bugs,
-  documentation will be appreciated just as much as code.
-- key criteria for code contributions are
-  - 'Code LESS: every line creates a work-chain. Code is a liability, not an 
-    asset'
-  - think hard before adding dependencies
-  - code should be tested and pass pep8
-
-## license
-
-- license is GPLv2 but other licensing can be considered on request
-- most of the copyright is currently Codethink but don't let that put you off.
-  There's no intent to keep this as a Codethink-only project, nor will there
-  be any attempt to get folks to sign a contributor agreement.
-  contributors retain their own copyright.
-