The current upgrade docs explain that the default behaviour of role mappers has changed and that the old behaviour can be reinstated, however it does not provide any guidance on what steps are required by the user in order for them to migrate their deployment(s) to the new behaviour. We should add such guidance to the docs.