Updated Versioning Strategy

  - Versioning is changing to a modified version of semver, see VERSIONS.md for more details.
  - Adds the UPGRADE.md guide
  - Changes the date format for the `5.x.x` line of changelogs.

3 files changed, 54 insertions, 42 deletions

diff --git a/CHANGES.md b/CHANGES.md
index 818bd43..e755916 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -1,10 +1,8 @@
 twilio-php Changelog
 ====================
 
-Version 5.1.1
--------------
-Released August 29, 2016
-
+[2016-08-29] Version 5.1.1
+--------------------------
 Changes the way that `uri`s are constructed to make sure that they are always 
 `rawurlencode()`d by the `twilio-php` library
 
@@ -12,10 +10,8 @@ Updates the output of the unit tests on failure introducing a new method,
 `assertRequest()`, that will output a friendlier error message when a request is
 missing in the `Holodeck` network mock.
 
-Version 5.1.0
--------------
-Released August 19, 2016
-
+[2016-08-19] Version 5.1.0
+--------------------------
 Optional arguments are handled in the `twilio-php` by accepting an associative 
 array of optional keys and values to pass to the API.  This makes it easy to 
 support all the optional parameters, but lessens developer ergonomics, since it 
@@ -73,32 +69,24 @@ arguments, so that you don't need to provided tons of default values.
 
 Both of these options work well with autocompleting IDEs.
 
-Version 5.0.3
--------------
-Released August 18, 2016
-
+[2016-08-18] Version 5.0.3
+--------------------------
 - Adds the ability to pass options into `Twilio\Http\CurlClient`.  This feature
   brings `CurlClient` closer to parity with `Services_Twilio_TinyHttp`.
 
-Version 5.0.2
--------------
-Released August 16, 2016
-
+[2016-08-16] Version 5.0.2
+--------------------------
 - Fixes a bug where reading lists with a `$limit` and no `$pageSize` would cause
   a divide by zero error.
 - Sanity check in the `Twiml` generator
 - Better tests for `Twiml` and `Version`
 
-Version 5.0.1
--------------
-Released August 15, 2016
-
+[2016-08-15] Version 5.0.1
+--------------------------
 Add the VERSIONS.md to explain the versioning strategy, first alpha release.
 
-Version 5.0.0
--------------
-Released August 15, 2016
-
+[2016-08-15] Version 5.0.0
+--------------------------
 **New Major Version**
 
 The newest version of the `twilio-php` helper library, supporting PHP 5.3+
diff --git a/UPGRADE.md b/UPGRADE.md
new file mode 100644
index 0000000..bfb1264
--- /dev/null
+++ b/UPGRADE.md
@@ -0,0 +1,5 @@
+# Upgrade Guide
+
+After `5.1.1` all `MINOR` and `MAJOR` version bumps will have upgrade notes 
+posted here.
+ 
diff --git a/VERSIONS.md b/VERSIONS.md
index f3c2cfb..27d6a7c 100644
--- a/VERSIONS.md
+++ b/VERSIONS.md
@@ -1,28 +1,45 @@
 # Versioning Strategy
 
-`twilio-php` uses [Semantic Versioning][semver] for all changes to the helper 
-library.  It is strongly encouraged that you pin at least the major version to 
-avoid pulling in breaking changes.
+`twilio-php` uses a modified version of [Semantic Versioning][semver] for all 
+changes to the helper library.  It is strongly encouraged that you pin at least 
+the major version and potentially the minor version to avoid pulling in breaking 
+changes.
 
 Semantic Versions take the form of `MAJOR`.`MINOR`.`PATCH`
 
 When bugs are fixed in the library in a backwards compatible way, the `PATCH` 
-level will be incremented by one.  `PATCH` changes should _not_ break your code 
-and are generally safe to upgrade to.
-
-When new features are added to the library in a backwards compatible way, the 
-`MINOR` level will be incremented by one and the `PATCH` level will be reset to
-zero.  `MINOR` changes are should _not_ break your code and are generally safe
-to upgrade to.  After a `MINOR` change you may wish to review the helper library
-for new features and functionality.
-
-When a bug or feature requires a breaking change, the `MAJOR` level will be 
-incremented by one and the `MINOR` and `PATCH` levels will reset to zero.  These
-changes can break your code.  Twilio understands that this can be very 
-disruptive, we will only introduce breaking changes when absolutely necessary. 
-Breaking changes will be communicated in advance with `Release Candidates` and a
+level will be incremented by one.  When new features are added to the library 
+in a backwards compatible way, the `PATCH` level will be incremented by one.
+`PATCH` changes should _not_ break your code and are generally safe for upgrade.
+
+When a new large feature set comes online or a small breaking change is 
+introduced, the `MINOR` version will be incremented by one and the `PATCH` 
+version reset to zero. `MINOR` changes _may_ require some amount of manual code
+change for upgrade, guidance will be provided in the [Upgrade Guide][upgrade]. 
+These backwards-incompatible changes will generally be limited to a small number 
+of function signature changes.
+
+The `MAJOR` version is used to indicate the family of technology represented by 
+the helper library.  It increased from `4.x.x` to `5.x.x` when Twilio moved to 
+auto generation of helper libraries.  Breaking changes that requires extensive 
+reworking of code (like the `4.x.x` to `5.x.x` upgrade) will case the `MAJOR` 
+version to be incremented by one, the `MINOR` and `PATCH` versions will be reset 
+to zero.  Twilio understands that this can be very disruptive, we will only 
+introduce this type of breaking change when absolutely necessary. New `MAJOR` 
+versions will be communicated in advance with `Release Candidates` and a 
 schedule.
 
+## Change Logs
+
+Twilio maintains a comprehensive [Changelog][changelog] for every version that 
+is released.  This will contain useful information every new version and what 
+bugs have been fixed, features added, and functionality enhanced.  After 5.1.1 
+Twilio will maintain an [Upgrade Guide][upgrade] for every change (`MINOR` or 
+`MAJOR`) that requires changes to your code.  When upgrading between two 
+versions that have more than a `PATCH` level change, it's best practice to check
+the [Upgrade Guide][upgrade] and to make sure that all your tests and static 
+checks pass after upgrade.
+
 ## Supported Versions
 
 `twilio-php` follows an evergreen model of support.  New features and 
@@ -56,4 +73,6 @@ in the stable artifact, with a `MAJOR` or `MINOR` version bump.
 To use an `Edge` artifact in your PHP project you will have to make sure that 
 you pin the artifact with `alpha` stability in your package.json.
 
-[semver]: http://semver.org/
\ No newline at end of file
+[semver]: http://semver.org/
+[changelog]: https://github.com/twilio/twilio-php/blob/master/CHANGES.md
+[upgrade]: https://github.com/twilio/twilio-php/blob/master/UPGRADE.md
\ No newline at end of file