diff options
Diffstat (limited to 'migrations/GUIDELINES')
| -rw-r--r-- | migrations/GUIDELINES | 35 |
1 files changed, 0 insertions, 35 deletions
diff --git a/migrations/GUIDELINES b/migrations/GUIDELINES deleted file mode 100644 index 3694e2c9..00000000 --- a/migrations/GUIDELINES +++ /dev/null @@ -1,35 +0,0 @@ -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`. |