diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 59 |
1 files changed, 59 insertions, 0 deletions
@@ -0,0 +1,59 @@ +Baserock reference system definitions +===================================== + +Baserock is a system for developing embedded and appliance Linux systems. For +more information, see <http://wiki.baserock.org>. + +These are some example definitions for use with Baserock tooling. You can fork +this repo and develop your own systems directly within it, or use it as a +reference point when developing your own set of definitions. + +These definitions follow the Baserock definitions format, which is defined in +spec.git repository (http://git.baserock.org/cgit/baserock/baserock/spec.git). + +The spec is readable online at <http://docs.baserock.org/spec>. + +The systems listed in the systems/ directory are example systems +that build and run at some point. The only ones we can be sure +that still build in current master of definitions are the ones that +we keep building in our ci system; they are listed in +http://git.baserock.org/cgit/baserock/baserock/definitions.git/tree/clusters/ci.morph + +Keeping up to date +------------------ + +The Baserock definitions format is evolving. A set of automated migrations is +provided in the migrations/ directory of spec.git, for use when the format has +changed and you want to bring your definitions up to date. + +Before running the migrations, you can use the 'migrations/indent' tool to +format the definitions in the specific style that the migrations expect. +The migrations use the 'ruamel.yaml' Python library for editing the .morph +files. This library preserves comments, ordering and some of the formatting +when it rewrites a .morph file. However, it does impose a certain line width +and indent style. + +It makes a lot of sense to run the migrations with a *clean Git working tree*, +so you can clearly see what changes they made, and can then choose to either +commit them, tweak them, or revert them with `git reset --hard` and write an +angry email. + +The suggested workflow is to run this from within your definitions.git clone: + + git clone git://git.baserock.org/baserock/baserock/spec ../spec.git + + git status # ensure a clean Git tree + ../spec/migrations/indent + git diff # check for any spurious changes + git commit -a -m "Fix formatting" + ../spec/migrations/run-all + git diff # check the results + git commit -a -m "Migrate to version xx of Baserock definitions format" + +If you are working in a fork of the Baserock definitions.git repo, you can +also keep to date with using changes in 'master' using `git merge`. In general, +we recommend first running the migrations, committing any changes they make, +*then* merging in changes using `git merge`. This should minimise the number of +merge conflicts, although merge conflicts are still possible. + +See migrations/GUIDELINES for information on how to write new migrations. |