Move to keep a changelog format

Fixes django-json-api#470

Includes documentation of versioning and deprecation policy

Author: Oliver Sauder

CHANGELOG.md

@@ -1,94 +1,155 @@
-[unreleased]
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Note that in line with [Django REST Framework policy](http://www.django-rest-framework.org/topics/release-notes/),
+any parts of the framework not mentioned in the documentation should generally be considered private API, and may be subject to change.
+
+## [Unreleased]
+
+### Added
 
 * Add testing configuration to `REST_FRAMEWORK` configuration as described in [DRF](https://www.django-rest-framework.org/api-guide/testing/#configuration)
 * Add `HyperlinkedRelatedField` and `SerializerMethodHyperlinkedRelatedField`. See [usage docs](docs/usage.md#related-fields)
 * Add related urls support. See [usage docs](docs/usage.md#related-urls)
-* Replaced binary `drf_example` sqlite3 db with a [fixture](example/fixtures/drf_example.yaml). See [getting started](docs/getting-started.md#running-the-example-app).
+* Add optional [jsonapi-style](http://jsonapi.org/format/) filter backends. See [usage docs](docs/usage.md#filter-backends)
+
+### Changed
+
+* Replaced binary `drf_example` sqlite3 db with a [fixture](example/fixtures/drf_example.json). See [getting started](docs/getting-started.md#running-the-example-app).
+
+### Deprecated
+
 * For naming consistency, renamed new `JsonApi`-prefix pagination classes to `JSONAPI`-prefix.
   * Deprecates `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination`
+
+### Fixed
+
 * Performance improvement when rendering relationships with `ModelSerializer`
-* Add optional [jsonapi-style](http://jsonapi.org/format/) filter backends. See [usage docs](docs/usage.md#filter-backends)
 
-v2.5.0 - Released July 11, 2018
+## [2.5.0] - 2018-07-11
+
+### Added
 
 * Add new pagination classes based on JSON:API query parameter *recommendations*:
   * `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination`. See [usage docs](docs/usage.md#pagination).
-  * Deprecates `PageNumberPagination` and `LimitOffsetPagination`
 * Add `ReadOnlyModelViewSet` extension with prefetch mixins
 * Add support for Django REST Framework 3.8.x
 * Introduce `JSON_API_FORMAT_FIELD_NAMES` option replacing `JSON_API_FORMAT_KEYS` but in comparison preserving
   values from being formatted as attributes can contain any [json value](http://jsonapi.org/format/#document-resource-object-attributes).
-   * `JSON_API_FORMAT_KEYS` still works as before (formatting all json value keys also nested) but is marked as deprecated
-* Performance improvement when rendering included data
 * Allow overwriting of `get_queryset()` in custom `ResourceRelatedField`
 
-v2.4.0 - Released January 25, 2018
+### Deprecated
+
+* Deprecate `PageNumberPagination` and `LimitOffsetPagination`. Use `JsonApiPageNumberPagination` and `JsonApiLimitOffsetPagination` instead.
+* Deprecate `JSON_API_FORMAT_KEYS`, use `JSON_API_FORMAT_FIELD_NAMES`.
+
+### Fixed
+
+* Performance improvement when rendering included data
+
+## [2.4.0] - 2018-01-25
+
+### Added
 
 * Add support for Django REST Framework 3.7.x.
 * Add support for Django 2.0.
+
+### Removed
+
 * Drop support for Django 1.8 - 1.10 (EOL)
 * Drop support for Django REST Framework < 3.6.3
   (3.6.3 is the first to support Django 1.11)
 * Drop support for Python 3.3 (EOL)
 
-v2.3.0 - Released November 28, 2017
 
-* Added support for polymorphic models
+## [2.3.0] - 2017-11-28
+
+### Added
+
+* Add support for polymorphic models
+* Add nested included serializer support for remapped relations
+
+### Changed
+
+* Enforcing flake8 linting
+
+### Fixed
 * When `JSON_API_FORMAT_KEYS` is False (the default) do not translate request
   attributes and relations to snake\_case format. This conversion was unexpected
   and there was no way to turn it off.
 * Fix for apps that don't use `django.contrib.contenttypes`.
 * Fix `resource_name` support for POST requests and nested serializers
-* Enforcing flake8 linting
-* Added nested included serializer support for remapped relations
 
-v2.2.0
+## [2.2.0] - 2017-04-22
+
+### Added
 
 * Add support for Django REST Framework 3.5 and 3.6
 * Add support for Django 1.11
 * Add support for Python 3.6
 
-v2.1.1
+## [2.1.1] - 2016-09-26
+
+### Added
 
-* Avoid setting `id` to `None` in the parser simply because it's missing
-* Fixed out of scope `relation_instance` variable in renderer
 * Allow default DRF serializers to operate even when mixed with DRF-JA serializers
-* Fixed wrong resource type for reverse foreign keys
-* Fixed documentation typos
 
-v2.1.0
+### Fixed
+
+* Avoid setting `id` to `None` in the parser simply because it's missing
+* Fix out of scope `relation_instance` variable in renderer
+* Fix wrong resource type for reverse foreign keys
+* Fix documentation typos
+
+## [2.1.0] - 2016-08.18
+
+### Added
 
 * Parse `meta` in JSONParser
-* Added code coverage reporting and updated Django versions tested against
-* Fixed Django 1.10 compatibility
-* Added support for regular non-ModelSerializers
-* Added performance enhancements to reduce the number of queries in related payloads
-* Fixed bug where related `SerializerMethodRelatedField` fields were not included even if in `include`
-* Convert `include` field names back to snake_case
+* Add code coverage reporting and updated Django versions tested against
+* Add support for regular non-ModelSerializers
+
+### Changed
+
 * Documented built in `url` field for generating a `self` link in the `links` key
-* Fixed bug that prevented `fields = ()` in a serializer from being valid
-* Fixed stale data returned in PATCH to-one relation
+* Convert `include` field names back to snake_case
 * Raise a `ParseError` if an `id` is not included in a PATCH request
 
-v2.0.1
+### Fixed
 
-* Fixed naming error that caused ModelSerializer relationships to fail
+* Fix Django 1.10 compatibility
+* Performance enhancements to reduce the number of queries in related payloads
+* Fix issue where related `SerializerMethodRelatedField` fields were not included even if in `include`
+* Fix bug that prevented `fields = ()` in a serializer from being valid
+* Fix stale data returned in PATCH to-one relation
 
-v2.0.0
+## [2.0.1] - 2016-05-02
 
-* Fixed bug where write_only fields still had their keys rendered
-* Exception handler can now easily be used on DRF-JA views alongside regular DRF views
-* Added `get_related_field_name` for views subclassing RelationshipView to override
-* Renamed `JSON_API_FORMAT_RELATION_KEYS` to `JSON_API_FORMAT_TYPES` to match what it was actually doing
-* Renamed `JSON_API_PLURALIZE_RELATION_TYPE` to `JSON_API_PLURALIZE_TYPES`
-* Documented ResourceRelatedField and RelationshipView
+### Fixed
+
+* Fixes naming error that caused ModelSerializer relationships to fail
+
+## [2.0.0] - 2016-04-29
+
+### Added
+
+* Add `get_related_field_name` for views subclassing RelationshipView to override
 * Added LimitOffsetPagination
 * Support deeply nested `?includes=foo.bar.baz` without returning intermediate models (bar)
 * Allow a view's serializer_class to be fetched at runtime via `get_serializer_class`
 * Added support for `get_root_meta` on list serializers
 
+### Changed
 
-v2.0.0-beta.2
+* Exception handler can now easily be used on DRF-JA views alongside regular DRF views
+* Rename `JSON_API_FORMAT_RELATION_KEYS` to `JSON_API_FORMAT_TYPES` to match what it was actually doing
+* Rename `JSON_API_PLURALIZE_RELATION_TYPE` to `JSON_API_PLURALIZE_TYPES`
+* Documented ResourceRelatedField and RelationshipView
 
-* Added JSONAPIMeta class option to models for overriding `resource_name`. #197
+### Fixed
 
+* Fixes bug where write_only fields still had their keys rendered