The guide details the general pitfalls such users may encounter when upgrading a patchwork. Upgrading older deployments of patchwork, particularly those that are pre-1.0, can be a daunting task and this guide should support users in this task. However, it should not replace the UPGRADING document but rather supplement it with more general, non-version specific advice.
Signed-off-by: Stephen Finucane <stephen.finuc...@intel.com> --- docs/upgrading.md | 119 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 2 files changed, 120 insertions(+) create mode 100644 docs/upgrading.md diff --git a/docs/upgrading.md b/docs/upgrading.md new file mode 100644 index 0000000..c50e032 --- /dev/null +++ b/docs/upgrading.md @@ -0,0 +1,119 @@ +# Upgrading + +**NOTE:** This document provides some general tips and tricks that one can use +when upgrading an existing, production installation of patchwork. If you are +interested in the specific changes between each release, please refer to the +[`UPGRADING` document][gh-upgrading] instead. If this is your first time +installing patchwork. please refer to the +[installation guide][doc-installation] instead. + +## Before You Start + +Before doing anything, always **backup your data**. This generally means +backing up your database, but it might also be a good idea to backup your +environment in case you encounter issues during the upgrade process. + +While patchwork won't explicity prevent it, it's generally wise to avoid +upgrades spanning multiple releases in one go. An iterative upgrade approach +will provide an easier, if slower, upgrade process. + +## Identify Changed Scripts, Requirements, etc. + +The `UPGRADING` document provides a comprehensive listing of all +backwards-incompatible changes that occur between releases of patchwork. +Examples of such changes include: + +* Moved/removed scripts and files +* Changes to the requirements, e.g. supported Django versions +* Changes to API that may affect, for example, third-party tools + +It is important that you understand these changes and ensure any scripts you +may have, such as systemd/upstart scripts, are modified accordingly. + +## Understand What Requirements Have Changed + +New versions of patchwork can often require additional or updated version of +dependencies, e.g. newer versions of Django. It is important that you +understand these requirements and can fulfil them. This is particularly true +for users relying on distro-provided packages, who may have to deal with older +versions of a package or may be missing a package altogether (though we try to +avoid this). Such changes are usually listed in the `UPGRADING` document, but +you can also diff the `requirements.txt` files in each release for comparison. + +## Ensure Your Database is Ready + +Migrations of the database can be tricky. Prior to [`v1.0.0`][gh-v1], database +migrations were provided by way of manual, SQL migration scripts. After this +release, patchwork moved to support [Django migrations][ref-django-migrate]. +If you are upgrading from `v1.0.0` or later, it is likely that you can rely +entirely on the later to bring your database up-to-date. However, there are a +number of scenarios in which you may need to fall back to the provided SQL +migrations or provide your own: + +* You are using Django < 1.6 + + patchwork supports Django 1.6. However, Django Migrations was added in 1.7 + and is [not available for previous versions][ref-south2]. As such, you must + continue to use manual migrations or upgrade your version of Django. + +* You are using Django > 1.6, but upgrading from patchwork < 1.0 + + patchwork only started providing migrations in `v1.0.0`. SQL migrations are + provided for versions prior to this and must be applied to get the database + to the "initial" state that Django migrations expects. + +* You have diverged from upstream patchwork + + If you have applied custom patches that change the database models, the + database in an "inconsistent state" and the provided migrations will likely + fail to apply. + +Steps to handle the latter two of these are described below. + +### Upgrading a pre-v1.0.0 patchwork instance + +The process for this type of upgrade is quite simple: upgrade using manual +SQL upgrades until better options become available. As such, you should apply +all unapplied SQL migrations that are not duplicated by Django migrations. +Once such duplication occurs, rely on the Django migrations only and continue +to do so going forward. + +### Upgrading a "diverged" patchwork instance + +This type of upgrade is a little trickier. There are two options you can take: + +1. Bring your patchwork instance back in sync with upstream +2. Provide your own migrations + +The former option is particularly suitable if you decide to upstream your +change or decide it's not valuable enough to retain. This will require either +reworking any migrations that exist prior to your feature being upstreamed, or +deleting any added database fields and tables, respectively. In both cases, +manually, hand-written SQL migrations will be required to get the databse into +a consistent state (remember: **backup**!). Once this is done, you can resume +using the upstream-provided migrations, ensuring any Django migrations that you +may have skipped are not applied again: + + ./manage.py migrate 000x-abc --fake # when 000x-abc is last "skippable" + +It's worth adding that with the databases now back in sync it should be +possible to return to using upstream code rather than maintaining a fork. + +The latter option is best chosen if you wish to retain the aforementioned fork. +How you do this depends on the extensiveness of your changes, but getting the +latest version of patchwork, deleting the provided migrations, applying any +patches you may have and regenerating the migrations seems like the best +option. + +**NOTE**: To prevent the latter case above from occuring, we'd ask that you +submit any patches you may have to the upstream patchwork so that the wider +community can benefit from this new functionality. Please see +[the contributing document][doc-contributing] for more informtion on this +process. + +[doc-installation]: installation.md +[doc-contributing]: contributing.md +[gh-upgrading]: https://github.com/getpatchwork/patchwork/blob/master/UPGRADING.md +[gh-v1]: https://github.com/getpatchwork/patchwork/releases/tag/v1.0.0 +[ref-django-migrate]: https://docs.djangoproject.com/en/1.8/topics/migrations/ +[ref-south2]: http://blog.allenap.me/2015/05/south-south-2-and-django-migrations.html diff --git a/mkdocs.yml b/mkdocs.yml index 89e6c78..fd31489 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -7,6 +7,7 @@ repo_url: git://github.com/getpatchwork/patchwork pages: - Home: 'index.md' - Installation: 'installation.md' + - Upgrading: 'upgrading.md' - Development: 'development.md' - Contributing: 'contributing.md' - Release Process: 'releasing.md' -- 2.0.0 _______________________________________________ Patchwork mailing list Patchwork@lists.ozlabs.org https://lists.ozlabs.org/listinfo/patchwork