Merge pull request #81 from github/kpaulisse-release-v1

Update documents for release 1.0.0

Author: kpaulisse

.version

@@ -1 +1 @@
-0.99.rc3
+1.0.0

README.md

@@ -8,10 +8,10 @@ At GitHub, we manage thousands of nodes with a Puppet code base containing 500,0
 
 `octocatalog-diff` is written in Ruby and is distributed as a gem. It runs on Mac OS and Unix/Linux platforms.
 
-**The current version of `octocatalog-diff` in the master branch is 0.99.rc3, a release candidate for version 1.0.**
-
 We consider the 1.x release of `octocatalog-diff` to be stable and production-quality. We continue to maintain and enhance `octocatalog-diff` to meet GitHub's internal needs and to incorporate suggestions from the community. Please consult the [change log](/doc/CHANGELOG.md) for details.
 
+If you've been using version 0.6.1 or earlier, please read about [What's new in octocatalog-diff 1.0](/doc/versions/v1.md) for a summary of new capabilities and breaking changes.
+
 ## How?
 
 Traditional Puppet development generally takes one of two forms. Frequently, developers will test changes by running a Puppet agent (perhaps in `--noop` mode) to see if the desired change has resulted on an actual system. Others will use formal testing methodologies, such as `rspec-puppet` or the beaker framework to validate Puppet code.

doc/CHANGELOG.md

@@ -8,44 +8,17 @@
 </tr>
 </thead><tbody>
 <tr valign=top>
-<td>0.99.0rc3</td>
-<td>2017-01-30</td>
+<td>1.0.0</td>
+<td>2017-02-06</td>
 <td>
-<ul>
-<li><a href="https://github.com/github/octocatalog-diff/pull/78">#78</a> Whitespace diff display enhancements</li>
-</ul>
-
-*This is the last planned release candidate unless problems are discovered.*
-</td>
-</tr>
-
-<tr valign=top>
-<td>0.99.0rc2</td>
-<td>2017-01-23</td>
-<td>
-<ul>
-<li><a href="https://github.com/github/octocatalog-diff/pull/70">#70</a> Missing `[]=` method in display code</li>
-<li><a href="https://github.com/github/octocatalog-diff/pull/77">#77</a> `FactOverride` -> `Override`</li>
-<li><a href="https://github.com/github/octocatalog-diff/pull/74">#74</a> Allow override of ENC parameters</li>
-</ul>
-</td>
-</tr>
-
-<tr valign=top>
-<td>0.99.0rc1</td>
-<td>2017-01-16</td>
-<td>
-This is a release candidate for `octocatalog-diff` version 1.0. Please report any problems to us as <a href="https://github.com/github/octocatalog-diff/issues/new">in a new issue</a>.
-
-The previous release (0.6.1) is available at: https://github.com/github/octocatalog-diff/tree/0.6.1
-
-<h4>New Features</h4>
-
-The most significant change in version 1.0 is the addition of the <a href="./dev/api.md">V1 API</a>, which permits developers to build catalogs (<code>--catalog-only</code>) and compare/diff catalogs using octocatalog-diff. Under the hood, we've rearranged the code to support these APIs, which should also improve the reliability and allow faster development cycles.
+This is the first release of the 1.0 series. For more information please see <a href="./versions/v1.md">What's new in octocatalog-diff 1.0</a>.
+<br>
+<br>
+The most significant change in version 1.0 is the addition of the <a href="./dev/api.md">V1 API</a>, which permits developers to build catalogs (<code>--catalog-only</code>) and compare/diff catalogs using octocatalog-diff. Under the hood, we've rearranged the code to support these APIs, which should improve the reliability and allow faster development cycles.
 
 <h4>Breaking Changes</h4>
 
-The format of the output from <code>--output-format json</code> has changed. In version 0.x of the software, each difference was represented by an array. In version 1.x, each difference is represented by a hash with meaningful English keys. We have added an option <code>--output-format legacy_json</code> if anyone depends upon the output in the old format.
+The format of the output from <code>--output-format json</code> has changed. In version 0.x of the software, each difference was represented by an array. In version 1.x, each difference is represented by a hash with meaningful English keys. We have added an option <code>--output-format legacy_json</code> for anyone who may depend on the old format.
 </td>
 </tr>
 <tr valign=top>

doc/versions/v1.md

@@ -0,0 +1,22 @@
+# What's new in octocatalog-diff 1.0
+
+#### Summary
+
+The most significant change in version 1.0 is the addition of the <a href="/doc/dev/api.md">V1 API</a>, which permits developers to build catalogs (<code>--catalog-only</code>) and compare/diff catalogs using octocatalog-diff. Under the hood, we've rearranged the code to support these APIs, which should also improve the reliability and allow faster development cycles.
+
+There are also some additional capabilities including:
+
+- Better display of whitespace differences
+- Override ENC parameters with `--to-enc-override` and `--from-enc-override`
+
+#### Breaking changes
+
+The format of the output from <code>--output-format json</code> has changed. In version 0.x of the software, each difference was represented by an array. In version 1.x, each difference is represented by a hash with meaningful English keys. We have added an option <code>--output-format legacy_json</code> which outputs in the old format.
+
+If you have written code that calls the octocatalog-diff command line and expects JSON output, you will need to update your code to the new format, or add or update `--output-format legacy_json` in your call to octocatalog-diff.
+
+#### API stability
+
+The API is versioned, and `v1` will be valid for all 1.x releases. We may add capabilities but will preserve existing functionality as it exists in the initial 1.0 release.
+
+Each API version change will correspond to a new major release number. In other words, a `v2` API would be introduced in a 2.0 release.