diff options
Diffstat (limited to 'migrations/GUIDELINES')
| -rw-r--r-- | migrations/GUIDELINES | 35 |
1 files changed, 35 insertions, 0 deletions
diff --git a/migrations/GUIDELINES b/migrations/GUIDELINES new file mode 100644 index 0000000..3694e2c --- /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`. |