debops
Migration/upgrade notes
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: https://github.com/olivierlacan/keep-a-changelog/issues/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: https://github.com/olivierlacan/keep-a-changelog/issues/34#issuecomment-62040018
Example: https://github.com/ypid/ansible-owncloud/blob/rework-3/UPGRADE.rst
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.
@drybjed Proposed to put the migration scrips into docs/scripts. This enhancement goes in line with https://github.com/debops/docs/issues/145. So this idea could have come from me :smile:
https://github.com/ypid/ansible-owncloud/blob/rework-3/docs/scripts/upgrade-from-v0.2.X-to-v0.3.X