Update changelog.

- Add tov2.md upgrade guide

CHANGELOG.md

@@ -5,15 +5,88 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ## [Unreleased]
 
-## [2.0.0] - 2018-01-??
-### Added
-### Changed
-### Deprecated
-### Removed
-### Fixed
-### Security
+## [2.0.0-rc2] - 2018-05-14
 
-## 2015-08-02
+Mostly rewrote Authboss by changing many of the core interfaces. This release
+is instrumental in providing better support for integrating with many web frameworks
+and setups.
+
+### Added
+
+- v2 Upgrade guide (tov2.md)
+
+- API/JSON Support
+
+    Because of the new abstractions it's possible to implement body readers,
+    responders, redirectors and renderers that all speak JSON (or anything else for that
+    matter). There are a number of these that exist already in the defaults package.
+
+### Changed
+
+- The core functionality of authboss is now delivered over a set of interfaces
+
+    This change was fairly massive. We've abstracted the HTTP stack completely
+    so that authboss isn't really doing things like issuing template renderings,
+    it's just asking a small interface to do it instead. The reason for doing this
+    was because the previous design was too inflexible and wouldn't integrate nicely
+    with various frameworks etc. The defaults package helps fill in the gaps for typical
+    use cases.
+
+- Storage is now done by many small interfaces
+
+    It became apparent than the old reflect-based mapping was a horrible solution
+    to passing data back and forth between these structs. So instead we've created a
+    much more verbose (but type safe) set of interfaces to govern which fields we need.
+
+    Now we can check that our structs have the correct methods using variable declarations
+    and there's no more confusion about how various types map back and forth inside the
+    mystical `Bind` and `Unbind` methods.
+
+    The downside to this of course is it's incredibly verbose to create a fully featured
+    model, but I think that the benefits outweigh the downsides (see bugs in the past about
+    different types being broken/not supported/not working correctly).
+
+- Support for context.Context is now much better
+
+    We had a few pull requests that kind of shoved context.Context support in the sides
+    so that authboss would work in Google App Engine. With this release context is
+    almost everywhere that an external system would be interacted with.
+
+- Client State management rewritten
+
+    The old method of client state management performed writes too frequently. By using a
+    collection of state change events that are later applied in a single write operation at
+    the end, we make it so we don't get duplicate cookies etc. The bad thing about this is
+    that we have to wrap the ResponseWriter. But there's an UnderlyingResponseWriter
+    interface to deal with this problem.
+
+- Validation has been broken into smaller and hopefully nicer interfaces
+
+    Validation needs to be handled by the BodyReader's set of returned structs. This punts
+    validation outside of the realm of Authboss for the most part, but there's still
+    helpful tools in the defaults package to help with validation if you're against writing
+    rolling your own.
+
+- Logout has been broken out into it's own module to avoid duplication inside login/oauth2
+  since they perform the same function.
+
+- Config is now a nested struct, this helps organize the properties a little better (but
+  I hope you never mouse over the type definition in a code editor).
+
+### Removed
+
+- Notable removal of AllowInsecureLoginAfterConfirm
+
+### Fixed
+
+- Fix bug where e-mail with only a textbody would send blank e-mails
+
+### Deprecated
+
+- Use of gopkg.in, it's no longer a supported method of consuming authboss. Use
+  manual vendoring, dep or vgo.
+
+## [1.0.0] - 2015-08-02
 ### Changed
 This change is potentially breaking, it did break the sample since the supporting struct was wrong for the data we were using.
 

tov2.md

@@ -0,0 +1,75 @@
+# Migrating to v2 from v1
+
+As always, the best way to understand most of this is to look at the
+[authboss-sample](https://github.com/volatiletech/authboss-sample). You could even look at
+the commits that lead from v1 to v2 (though it is not divided nicely into small commits).
+
+## Configuration
+
+The configuration has been changed drastically from an API perspective as it's now sub-divided
+with substructs into pieces. But in general the same options should be available with few exceptions.
+
+In most cases the replacements will be very straightforward, and if you were using the default values
+nothing much should have to change.
+
+## HTTP Stack (and defaults package)
+
+The HTTP stack has been ripped apart into several small interfaces defined in the config struct.
+Before you panic when you see Responder, Redirector, BodyReader etc, it's important to see the
+`defaults` package in Authboss. This package contains sane default implementations for all of
+these components (with the exception of an html renderer, though a JSON one is present).
+
+You probably will not want to override any of these and so I'd suggest a peek at the method
+`default.SetCore` (used in the sample as well) that sets up these default implementations
+easily.
+
+There is also an HTML renderer available at
+[authboss-renderer](https://github.com/volatiletech/authboss-renderer).
+
+## Server storage
+
+### Understanding User vs Storer
+
+In the past Authboss used extremely confusing terminology and sort of a conflated
+design of User and Storer (database). In v2 these concepts have been separated and
+there is now a User interface and a ServerStorer interface. These two interfaces represent
+the concepts of the User data, and the Server storage mechanism that loads and saves
+users.
+
+The user interface is now implemented without reflection. Previously in Authboss we would
+scrape the values from your struct, and update them via reflection as well. This is extremely
+error prone and relies on hardcoded types everywhere and it just generally was a bad idea.
+Despite the verbosity of using methods for every single field value we want, it's type safe
+and provides a great spot for doing type conversions between whatever you're using in your
+struct/database and whatever authboss wants for talking to web clients.
+
+### ServerStorer
+
+This interface simply needs to Load and Save Users at the outset. Just like before there
+are upgraded interfaces that are required by other modules, for example the `recover` module
+wants a `RecoveringServerStorer` which has the method `LoadByRecoverToken` which you'll have
+to add to your storer.
+
+### User
+
+Your user struct should be able to remain the same, and all you need to do is add the methods
+required for getting and setting the fields. Remember the methods are dictated by the interfaces
+required by the modules you're loading (see authboss README.md for more details). For example
+the `auth` module requires an `AuthableUser` which requires `Get|PutPassword` methods.
+
+## Client state
+
+The client state interfaces have been rewritten to do a just-in-time write to the response
+before the headers are completely flushed. This makes sure we only Read and only Write the
+client state (cookies/sessions) one time. It requires a new middleware `LoadClientStateMiddleware`
+which wraps the responsewriter with a new one that has the ability to manage client state.
+
+In the ClientStateReadWriter interface (the one you now implement to handle sessions and cookies)
+you now return a ClientState interface (basically a map of values) that represents a snapshot of the
+state of the client when the request was initially read, this ensures that code will use the context
+for value passing and not the session as an added bonus. But basically caches the client state
+values for the remainder of the request.
+
+Events are written to the ResponseWriter and eventually the `WriteState` method is called and give
+the old state and the events that occurred during request processing, asks for a new state to be
+written out to the responsewriter's headers.