diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md index 497c9154f..066333b6c 100644 --- a/docs/maintenance-upgrading-services.md +++ b/docs/maintenance-upgrading-services.md @@ -1,10 +1,10 @@ @@ -40,9 +40,21 @@ If you don't have either `just` tool or `make` program, you can run the `ansible **Note**: for details about `just` commands, take a look at: [Running `just` commands](just.md). +### Acknowledge breaking changes if any + +The playbook uses a migration validation system that ensures you are aware of breaking changes before they'll affect your deployment. If there is one, you are required to acknowledge each breaking change. + +Whenever a breaking change is introduced, the playbook will: + +- bump its expected version value (`matrix_playbook_migration_expected_version`), causing a discrepancy with what you validated (`matrix_playbook_migration_validated_version`) + +- fail when you run it with a helpful message listing what changed and linking to the relevant changelog entries + +After reviewing and adapting your setup, update the variable to the new version. + ### Re-run the playbook setup -After updating the Ansible roles, then re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services: +After updating the Ansible roles and the variable for the validation system when necessary, re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services: ```sh ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start