[PATCH 1/3] CHANGELOG: Integrate UPGRADING content

Tue Sep 20 08:37:49 AEST 2016

Rewrite the CHANGELOG as necessary, making better use of the
'UPGRADING' section

Signed-off-by: Stephen Finucane <stephenfinucane at hotmail.com>
---
 CHANGELOG.md | 106 ++++++++++++++++++++++++++++++++++++++++++++++-------------
 UPGRADING.md |  87 ++----------------------------------------------
 2 files changed, 85 insertions(+), 108 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 286ae6a..f0b81c9 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,60 +13,120 @@ This project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [1.1.0] - 2016-03-03
 
+This release overhauled the web UI and added support for automatic delegation
+of patches, test result capture, and Python 3.4.
+
 ### Added
 
-- Python 3 support
-- Web UI overhaul
+- Python 3.4 support
 - Check feature, which can be used to report the status of tests
 - Automatic delegation of patches based on file path
 - Automated documentation for the XML-RPC API. This can be found at the
   '/xmlrpc' in most Patchwork deployments
-- Selenium-based UI tests
 - Vagrant support for developers
-- Assorted cleanup tasks and bug fixes
+- Selenium-based UI tests for developers
 
 ### Changed
 
+- Overhauled the web UI to reflect modern web standards
 - Patches can now be delegated to any Patchwork user
 - Significant updates to the documentation
+- Assorted cleanup tasks and bug fixes
 
 ## [1.0.0] - 2015-10-26
 
 ### Added
 
-- Patch tag infrastructure feature. This provide a quick summary of patch
-  'tags' (e.g. `Acked-by`, `Reviewed-by`, ...) found in a patch and its replies
-- Support for Django 1.7 and Django 1.8
-- Support for Django Migrations. This will be the chosen method of making
-  database changes going forward. See below for more information
-- Support for tox
-- Django management commands, which replace the existing Patchwork cron scripts
-- CHANGELOG.md and UPGRADING.md docs
+- Patch tag infrastructure feature, which provides a quick summary of patch
+  "tags" (e.g. `Acked-by`, `Reviewed-by`, ...) found in a patch and its replies
+- Django 1.7 and Django 1.8 support
+- Django `staticfiles` support, which should be used to gather static files for
+  for serving via a web server
+- tox support for developers
 
 ### Changed
 
-- Static files are now gather and served using the `django.contrib.staticfiles`
-  module, per Django best practices
-- Restructured directory per modern Django standards. The `apps` directory no
-  longer exists and Patchwork source has instead been moved to the top level
-  directory
+- Migrations are now executed using the Django migrations framework
+- Moved Patchwork source from the `apps` directory to the top level directory
+- The `cron` Django management command has replaced the `bin/patchwork-cron`
+  script
 - Rewrote documentation to reflect changes in development and deployment best
   practices over the past few years
 - Reworked `requirements.txt` and `settings.py` files
 
 ### Removed
 
-- Support for Django 1.5
+- Django 1.5 support
 - Defunct Python 2.5 code
 - Numerous dead files/code
-- `bin/patchwork-cron` script, in favor of `cron` management command
 
 ### Deprecated
 
-- Django 1.6 support will be removed in the next release
-- Django 1.7 supports Django Migrations and Django 1.8 requires them. This
-  negates the need for handwritten SQL migration scripts. Future releases will
-  no longer include these scripts and they will eventually be removed
+- Django 1.6 support will be removed in a future release
+- Raw SQL migration scripts, previously found at `lib/sql/migration`, will no
+  longer be provided. Use the Django Migration framework found in Django 1.7
+  and above
+
+### Additional notes
+
+This version changes a few admin-visible components of Patchwork, so upgrading
+involves a few steps.
+
+#### Update settings
+
+By default, settings are read from `patchwork/settings/production.py`. To
+migrate, use the provided template:
+
+    $ cp patchwork/settings/production{.example,}.py
+
+Merge your previous settings, usually located in `apps/local_settings.py`, to
+this file.
+
+#### Fix external references
+
+Any scripts or tools that call Patchwork applications, such as `parsemail.sh`,
+must be updated to reference the new location of these scripts. To do this,
+simply remove `apps/` from the path, i.e. `apps/patchwork/` becomes
+`patchwork`.
+
+In addition, any scripts that set the `DJANGO_SETTINGS_MODULE` environment
+variable will need to be updated to reflect the new location, typically:
+
+    DJANGO_SETTINGS_MODULE=patchwork.settings.production
+
+Finally, as the `patchwork-cron.py` script has been replaced by the `cron`
+management command, any references to the former should be updated to the
+latter. The `cron` management command can be called like so:
+
+    $ ./manage.py cron
+
+#### Migrate to Django Migrations
+
+Future database migrations will be implemented using Django Migrations, rather
+than raw SQL scripts. Before switching to Django migrations, first apply any
+unapplied migrations in the `lib/sql/migration` folder. For example, on
+postgres:
+
+    $ psql -f lib/sql/migration/015-add-patch-tags.sql patchwork
+    $ psql -f lib/sql/grant-all.postgres.sql patchwork
+
+Once applied, configure the required Django Migration tables using the
+`migrate` managment command:
+
+    $ ./manage.py migrate --fake-initial
+
+#### Migrate to Django Staticfiles
+
+Static content should now be located in the folder indicated by `STATIC_ROOT`.
+This should point to somewhere sensible, such as the absolute path of
+`htdocs/static` in the Patchwork tree. Configure the `STATIC_ROOT` setting in
+your settings file, then run the `collectstatic` management command:
+
+    $ ./manage.py collectstatic
+
+Finally, update your webserver's configuration to serve the static content from
+this new location. Refer to the sample web configuration files provided in
+`lib` for more information.
 
 ## [0.9.0] - 2015-03-22
 
diff --git a/UPGRADING.md b/UPGRADING.md
index 35c75e5..1089194 100644
--- a/UPGRADING.md
+++ b/UPGRADING.md
@@ -1,87 +1,4 @@
 # Patchwork Upgrade Guide
 
-## 1.0.0 to 1.1.0
-
-Version 1.1.0 adds a number of new features, but many of these will require
-little to no changes.
-
-## 0.9.0 to 1.0.0
-
-Version 1.0.0 changes a few admin-visible components of Patchwork so
-upgrading involves a few steps.
-
-### Database Migrations
-
-Update the database schema, by running the `015-add-patch-tags.sql` script,
-and re-run the grants script. For example, on postgres:
-
-    psql -f lib/sql/migration/015-add-patch-tags.sql patchwork
-    psql -f lib/sql/grant-all.postgres.sql patchwork
-
-We highly suggest you move to Django Migrations as support for Django 1.6
-(and subsequently manual SQL migrations) will be dropped in an upcoming
-release. You can do this using the migrate command:
-
-    ./manage.py migrate --fake-initial
-
-**NOTE**: The `--fake-initial` parameter is only required on Django >= 1.8.
-
-### Update to the new settings infrastructure
-
-By default, settings are read from `patchwork/settings/production.py`. To
-migrate, use the template:
-
-    cp patchwork/settings/production{.example,}.py
-
-Merge your previous settings (from `apps/local_settings.py`) into this file.
-
-### Fixup external references to `apps/`
-
-The `apps/` directory is gone; the Patchwork module is now in the top-level
-directory. If you have scripts that run anything from `apps/` (e.g. incoming
-mail parsers that call `parsemail.sh`, and cron scripts), then remove the
-`apps/` directory from those:
-
-    apps/patchwork/ -> patchwork/
-
-Alternatively, you can create a symlink - `apps/ -> .`
-
-If you have been running scripts (eg, from cron) that set the
-`DJANGO_SETTINGS_MODULE` environment variable, you'll need to update that to
-the new settings system. Typically:
-
-    DJANGO_SETTINGS_MODULE=patchwork.settings.production
-
-The `manage.py` script has been moved from apps/ into the top-level directory
-too.
-
-### Migrate to the `staticfiles` module
-
-Static content should now be located in the folder indicated by `STATIC_ROOT`.
-This should point somewhere sensible (e.g. the absolute path of `htdocs/static`
-in the Patchwork tree).
-
-You'll need to set the `STATIC_ROOT` setting in your settings file.
-
-Once settings are configured, run the 'collectstatic' management command:
-
-    ./manage.py collectstatic
-
-You also need to update your Apache configuration to use the new static
-content. Since static content is now in all under `STATIC_ROOT`, the
-configuration should be simpler than in previous releases. The core config
-will be:
-
-    DocumentRoot /srv/patchwork/htdocs/
-    Alias /static/ /srv/patchwork/htdocs/static/
-    WSGIScriptAlias / /srv/pathchwork/lib/apache2/patchwork.wsgi
-    WSGIPassAuthorization On
-
-### Use new management console
-
-The Patchwork cron script (`bin/patchwork-cron.py`) has been moved to a
-`manage.py` command. Instead of running `patchwork-cron.py`, you should now
-run:
-
-    ./manage.py cron
-
+For information on upgrading Patchwork instances, refer to the
+[changelog](./CHANGELOG.md).
-- 
2.7.4

