Add a changelog (also consists of the migration guide for 2)

[skip ci]

closes #121
closes #217

2 files changed, 139 insertions, 10 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
new file mode 100644
index 0000000..313e712
--- /dev/null
+++ b/CHANGELOG.md
@@ -0,0 +1,129 @@
+# UNRELEASED
+
+This release represents a major version bump: many new features have
+been added and large parts of the codebase have been refactored.
+Although a lot of effort has gone into keeping API changes minimal,
+this release is unfortunately not source or binary compatible with the
+1.x versions.
+
+The following is a list of major changes. Please see the git commit
+log `git log 1.x..v2.0.0` for details.
+
+## Structural Changes
+
+The core project has been split into many modules, as described in the
+README, each having distinct functionality.
+
+In a nutshell, packages in `xyz.driver.core` have been moved to
+separate sbt projects. For example, all classes contained in
+`xyz.driver.core.messaging` have been moved to the project
+`core-messaging`, and `xyz.driver.core.storage` to
+`core-storage`. Thus, the modules providing utilities from the latest
+1.x version are:
+
+- `core-database`
+- `core-rest`
+- `core-messaging`
+- `core-storage`
+
+Along those functional modules, there are the supporting modules:
+
+- `core-types`, which contains common types, such as `time`, `date`
+  and IDs
+- `core`, which contains the `app` initialization system and also
+  depends on all other modules, acting as an indirection for
+  backwards-compatibility.
+
+Furthermore, some new modules have been added which will be explained
+later on:
+
+- `core-reporting` (tracing and logging utilities)
+- `core-init` (new initialization framework)
+- `core-testkit` (core-specific parts of driver-test-utils)
+
+The split was done in order to reduce coupling between components. Our
+internal domain-model now only depends on `core-rest` and
+`core-messaging`. Services can choose if and what other parts of core
+to use, although it is recommended they use the `core-init` module.
+
+Although the split was mostly seemless, some cyclic dependencies
+between packages were discovered. Since these are no longer possible
+in a multi-project architecture, some source-breaking changes also had
+to made. These will be listed later and marked as such.
+
+## New Features
+
+### Reporting Utilities
+
+A suite of tracing and logging utilities, based on the OpenTrace
+specification, have been added as the `core-reporting` module. This
+module plays a central role because it greatly simplifies debugging
+distributed applications, and as such is depended upon by all other
+modules.
+
+It embraces the "implicit context" pattern, and requires a
+`SpanContext` for all logging actions. This context can be thought of
+as a more type-safe "Message Diagnostic Context" and also replaces the
+slf4j-based MDC utilities in previous versions of core.
+
+### Typeclass-based service discovery
+
+A type-class based service discovery has been added in
+`xyz.driver.rest.DnsDiscovery`. It allows seemless instantiation of
+client implementations that provide a "Service Descriptor" type
+class. It also does not require any configuration (except for
+overrides) and uses the DNS to resolve service hosts.
+
+### Initialization Framework
+
+A trait-based initialization framework has been added in
+`core-init`. It implements common application startup procedures and
+initializes common utilities for cloud-based web services. It
+integrates all other core modules in an idiomatic way.
+
+## API-Breaking Changes
+
+Due to the structural changes mentioned previously, some API-breaking
+changes were made:
+
+- `xyz.driver.rest.errors.DatabaseException` has been moved to
+  `xyz.driver.core.DatabaseException`, into the project
+  `core-types`. This move happened because both the `rest` and
+  `database` module require this exception.
+
+- `xyz.driver.core.FutureExtensions` has been moved to
+  `xyz.driver.core.rest` as it only contained logic that dealt with
+  service exceptions, something that belongs into `core-rest` and must
+  not be depended upon by `core-types`.
+
+- all classes but `AuthStub` in `xyz.driver.test` have been moved to
+  `xyz.driver.core.testkit` and are available in th
+  `core-testkit`. *(`AuthStub` has been moved to
+  `xyz.driver.users.testkit` in the project `users-testkit` in the
+  users service repo)*
+
+## Deprecation Notices
+
+Several major features have been deprecated and will be removed in the future.
+
+- `xyz.driver.core.app` will stop receiving updates as `xyz.driver.core.init` matures
+
+- `xyz.driver.core.time` and `xyz.driver.core.date` will be replaced
+  by their java 8 counterparts
+
+- the initial object-storage utilities in `xyz.driver.core.file` will
+  be removed in favor of the ones provided in `core-storage`
+
+- the first version of the message bus api `xyz.driver.core.pubsub`
+  will be replaced by `core-messaging`
+
+- `xyz.driver.driver.logging` will be removed as it is made obsolete
+  by `core-reporting`
+  
+Deprecation of other classes in the [`core` support
+module](src/main/scala/xyz/driver/core) is yet to be
+determined. Please open an issue if you have any comments on them.
+
+# Version 1.x
+
+Please see git commit logs for changes prior to version 2.
diff --git a/README.md b/README.md
index 22cecd0..ec0050a 100644
--- a/README.md
+++ b/README.md
@@ -42,16 +42,16 @@ specific functionality.
 
 Project          | Description
 -----------------|------------
-`core`           | *(deprecated)* Previous application initialization framework.
-`core-database`  | Utilities for working with databases, slick in particular.
-`core-init`      | Mini-framework that offers default instances of many utilities, configured for the current platform.
-`core-messaging` | Library for abstracting over message buses such as Google PubSub.
-`core-reporting` | Combined tracing and logging library.
-`core-rest`      | Abstractions to represent RESTful services, discovery and client implementations.
-`core-storage`   | Object storage utilities.
-`core-testkit`   | Mixins for scalatest.
-`core-types`     | Type definitions that are commonly used by applications.
-`core-util`      | Other utilities that do not belong anywhere else. **Note that this is a staging place for code that does not have its own submodule yet. Do not depend on it externally!**
+core           | *(deprecated)* Previous application initialization framework.
+core‑database  | Utilities for working with databases, slick in particular.
+core‑init      | Mini-framework that offers default instances of many utilities, configured for the current platform.
+core‑messaging | Library for abstracting over message buses such as Google PubSub.
+core‑reporting | Combined tracing and logging library.
+core‑rest      | Abstractions to represent RESTful services, discovery and client implementations.
+core‑storage   | Object storage utilities.
+core‑testkit   | Mixins for scalatest.
+core‑types     | Type definitions that are commonly used by applications.
+core‑util      | Other utilities that do not belong anywhere else. **Note that this is a staging place for code that does not have its own submodule yet. Do not depend on it externally!**
 
 These components and their internal dependencies can be represented
 with the following graph.