Migration/upgrade notes

[ypid]

Related to the redesign of the changelog format in #154 it might also be a good idea to think about migration/upgrade notes.
http://keepachangelog.com/ also has a discussion about that: olivierlacan/keep-a-changelog#34

Previously used:

• Inline in the changelog entries: http://docs.debops.org/en/latest/ansible/roles/ansible-apt/docs/changelog.html#v0-2-0
• Separate section in the changelog: http://docs.debops.org/en/latest/ansible/roles/ansible-mariadb_server/docs/changelog.html#migration-notes

I would propose keeping a separate UPGRADE.rst file when needed in the root of the repo and integrate it into the docs after the changelog.
Reasons for a separate changelog: olivierlacan/keep-a-changelog#34 (comment)

Example: https://github.com/ypid/ansible-owncloud/blob/rework-3/UPGRADE.rst

[drybjed]

Sure, separate file in the root directory (easily visible) describing any needed upgrade steps sounds good. I don't think that it needs to always be present, only when we know that some manual upgrade steps are needed or expected.

[ypid]

Agreed 😉 Done.

[ypid]

@drybjed Proposed to put the migration scrips into docs/scripts. This enhancement goes in line with #145. So this idea could have come from me 😄

https://github.com/ypid/ansible-owncloud/blob/rework-3/docs/scripts/upgrade-from-v0.2.X-to-v0.3.X