Improve documentation around migration safety

[ivanbakel]

The Haddocks around CautiousMigration were ambiguous, since it wasn't clear if the flag signified whether each migration was safe or not - and there is at least one instance in the code that gets it wrong.

This corrects that error, opting to make the addMigration documentation match the code's behaviour.

Personally, I think the better approach to this mess would be to replace all the use of (Bool, Text) with a datatype that enforces better usage through a stricter API - something like

data CautiousSql = MkCautiousSql { ... } -- Hide this constructor

-- Expose these smart constructors
mkSafeSql :: Sql -> CautiousSql
mkSafeSql = ...

mkUnsafeSql :: Sql -> CautiousSql
mkUnsafeSql = ...

-- Expose these instead of record fields
isUnsafe :: CautiousSql -> Bool
isUnsafe = ...

rawSql :: CautiousSql -> Sql
rawSql = ...

-- Maybe even a smart destructor?
ifSafe :: (Bool -> Sql -> a) -> CautiousSql -> a
ifSafe = ...

That way consumers could not be misled about the nature of the Bool value. But I thought that would be quite drastic and breaking, so I didn't want to make it my first suggestion.

Fixes #1081.

Before submitting your PR, check that you've:

• Documented new APIs with Haddock markup
• Added @since declarations to the Haddock
• Ran stylish-haskell on any changed files.
• Adhered to the code style (see the .editorconfig file for details)

After submitting your PR:

• Update the Changelog.md file with a link to your PR
• Bumped the version number if there isn't an (unreleased) on the Changelog
• Check that CI passes (or if it fails, for reasons unrelated to your change, like CI timeouts)

[ivanbakel]

I've discovered this fixes an issue, so I'll add that into the PR message.

[parsonsmatt]

Let's make this a documentation change instead of a behavior change. That way we can release it as a patch fix. If we're changing behavior, that'd need to be in a major version bump.

[parsonsmatt]

This would be a breaking change in behavior. Let's instead change the documentation? That way, we won't break any existing code, and folks writing new code will be able to tell from the docs how to do it right.

[ivanbakel]

This is done now.

[parsonsmatt]

looks great! persistent-2.13.0.3 was released since, but I'll get this out as persistent-2.13.0.4.