Commit 65bd91f4 authored by Paul Sherwood's avatar Paul Sherwood

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
parents d8aba233 4b02337d
Pipeline #4588798 passed with stages
in 7 minutes and 49 seconds
This diff is collapsed.
## 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
## 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
```
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.
# 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.
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment