Add migration scripts for historical versions of the definitions format

See README for more information on how the migrations are intended work.

These migrations are probably not widely useful, as our definitions have
already been migrated manually. However, I want to come up with a good
pattern for writing migration scripts, and actually doing it seems like
the best way.

There is a 'migrations/indent' tool, which reformats a set of
definitions according to how the ruamel.yaml program writes them out.
This tool is nice if you like everything to have consistent indent and
line wrapping, and you can run it before running the migrations to
ensure that the migrations don't do any reformatting when writing the
.moprh files back to disk.

The migration scripts require the ruamel.yaml Python library. I have
sent a separate change to add this to the 'build' and 'devel' reference
systems.

Change-Id: Ibd62ba140d3f7e8e638beed6d714f671405bdc79

1 files changed, 35 insertions, 0 deletions

diff --git a/migrations/GUIDELINES b/migrations/GUIDELINES
new file mode 100644
index 00000000..3694e2c9
--- /dev/null
+++ b/migrations/GUIDELINES
@@ -0,0 +1,35 @@
+Guidelines for writing migrations
+---------------------------------
+
+All changes to the definitions format must have a migration, but it is valid
+for the migration to do nothing except update the version number (see
+004-install-files-overwrite-symlink.py for an example of that).
+
+This small set of rules exists to ensure that the migrations are consistent and
+easy to understand. If you are writing a migration and these rules don't make
+any sense, we should probably change them. Please sign up to the
+baserock-dev@baserock.org mailing list to suggest the change.
+
+- Write migrations in Python. They must be valid Python 3. For now, since
+  only Python 2 is available in Baserock 'build' and 'devel' reference systems
+  up to the 15.25 release of Baserock, they must also be valid Python 2.
+
+- Don't use any external libraries.
+
+- Follow the existing file naming pattern, and the existing code convention.
+
+- Keep the migration code as simple as possible.
+
+- Avoid crashing on malformed input data, where practical. For example, use
+  contents.get('field') instead of contents['field'] to avoid crashing when
+  'field' is not present. The idea of this is to avoid a "cascade of errors"
+  problem when running the migrations on bad inputs. It is confusing when
+  migrations break on problems that are unrelated to the actual area where
+  they operate, even if they are theoretically "within their rights" to do so.
+
+- Migrate the definitions in line with current best practices. For example,
+  migrations/001-empty-build-depends.py doesn't need to remove empty
+  build-depends fields: they are still valid in version 1 of the format. But
+  best practice is now to remove them. Users who don't agree with this practice
+  can choose to not run that migration, which can be done with `chmod -x
+  migrations/xxx.py`.