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`.