This document describes why Flyway versioning is needed and a list of versions which can be reserved by developers.
Flyway requires that a migration has a unique and incremental version. This implies that The DHIS 2 version notation follows this format:
V2_<DHIS 2 major version>_<Incrementing number>__<Description>.(sql|java)
Flway migrations are applied in order exactly once. Flyway migrations should not be changed after being commited or applied in a way that changes the checksum of the migration, as it will cause the startup process to fail.
When working on multiple pull requests concurrently, there is a chance of those PRs being applied in a way where more than one PR uses the same migration version. To mitigate this problem, DHIS 2 developers should reserve a version in this document once a PR which contains a migration is raised.
It is important to take into account:
- The reservation should not be done too early, as it will make it more complex to merge. Make the reservation at the time of raising the PR for review.
- PRs which contain migrations must be merged in the order of the migration versions. This is done so that migrations will be applied in the appropriate, ascending order.
Regarding backports of Flyway migrations, extreme caution must be taken in order to avoid issues. Only critical Flyway migrations should be backported and we should stay on the conservative side. For non-critical clean-ups, SQL scripts can be made available and run manually.
The table below contains a list of migration versions. Please reserve the appropriate version using the migration version and the link to the corresponding Jira issue or PR.