[PATCH 1/2] doc: Add CHANGELOG and UPGRADING docs

Sat Oct 17 09:00:22 AEDT 2015

The CHANGELOG document should describe the high level changes of the
project. This will provide a human-readable way for people to evaluate
the changes in each release. This file is based on the templates and
general changelog "ethos" provided by 'Keep a CHANGELOG':

    http://keepachangelog.com/

The UPGRADING document provide instruction for system admininstrators
managing patchwork deployments. At the moment, this document is a
rename and minor reformatting of the existing 'docs/NEWS' document, but
going forward documentation will be added for each new release.

Signed-off-by: Stephen Finucane <stephen.finucane at intel.com>
---
 CHANGELOG.md | 57 ++++++++++++++++++++++++++++++++++++++++++++++
 UPGRADING.md | 74 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 docs/NEWS    | 67 ------------------------------------------------------
 3 files changed, 131 insertions(+), 67 deletions(-)
 create mode 100644 CHANGELOG.md
 create mode 100644 UPGRADING.md
 delete mode 100644 docs/NEWS

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..f28a7b5
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,57 @@
+# Change Log
+
+All notable changes to this project will be documented in this file. Please
+refer to the release notes for more detailed information, e.g. how to upgrade.
+
+This project adheres to [Semantic Versioning](http://semver.org/).
+
+## [Unreleased]
+
+...
+
+## [1.0.0] - 2015-10-16
+
+### 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
+
+### 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
+- 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
+- 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
+
+## [0.9.0] - 2015-03-22
+
+**NOTE:** 1.0.0 was the first release of patchwork adopting semantic versioning.
+For information on *"0.9.0"* and before, please refer to Git logs.
+
+[Unreleased]: https://github.com/getpatchwork/patchwork/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/getpatchwork/patchwork/compare/v0.9.0...v1.0.0
+[0.9.0]: https://github.com/getpatchwork/patchwork/compare/c561ebe...v0.9.0
+
diff --git a/UPGRADING.md b/UPGRADING.md
new file mode 100644
index 0000000..3cf69d4
--- /dev/null
+++ b/UPGRADING.md
@@ -0,0 +1,74 @@
+# Patchwork Upgrade Guide
+
+## 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
+
+### 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
+
diff --git a/docs/NEWS b/docs/NEWS
deleted file mode 100644
index d1342b1..0000000
--- a/docs/NEWS
+++ /dev/null
@@ -1,67 +0,0 @@
-== Cron script changes ==
-
-The patchwork cron script has been moved to a manage.py command. Instead
-of running patchwork-cron.py, run:
-
-  ./manage.py cron
-
-== Upgrading to 3b8a61c ==
-
-Recent commits have changed a few admin-visible components of patchwork, so
-upgrading to post-commit 3b8a61c involves a few steps:
-
-- 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
-
-- 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
-
-  and 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/ (eg, incoming
-  mail parsers that call parsemail.sh, and cron scripts), then remove the apps/
-  directory from those.
-
-    apps/patchwork/ -> patchwork/
-
-  (or you can create a symlink - apps/ -> .)
-
-- Update any external scripts to use the new settings module
-
-  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.
-
-- Run the 'collectstatic' management command:
-
-    ./manage.py collectstatic
-
-  Ensure that the STATIC_ROOT setting points somewhere sensible (eg, the
-  absolute path of htdocs/static in the patchwork tree).
-
-- Update apache to use the new static content.
-
-  Static content is now in all under STATIC_ROOT, the apache configuration
-  should be simpler now. The core config will be:
-
-        DocumentRoot /srv/patchwork/htdocs/
-        Alias /static/ /srv/patchwork/htdocs/static/
-        WSGIScriptAlias / /srv/pathchwork/lib/apache2/patchwork.wsgi
-        WSGIPassAuthorization On
-
-- 
2.0.0

