Merge branch 'master' into feature-dnc

# Conflicts:
#	readme.md

CONTRIBUTING.md

@@ -0,0 +1,9 @@
+## Do not create new issues here directly
+
+If you've found a bug or something isn't working, please quickly check these issues and 
+our [main issue repository](https://github.com/OctopusDeploy/Issues). If you think you have found a new issues, or need some help, 
+please [contact support](http://octopusdeploy.com/support). We don't read new GitHub issues regularly, so if you post here it will likely not get a reply. But if you contact support we can probably help to find a workaround or make sure the issue gets prioritized properly. 
+
+
+
+If you have an idea or a feature request, please post it to [our UserVoice site](http://octopusdeploy.uservoice.com) so others can vote for it. 

gitversion.yml

@@ -1 +1 @@
-mode: Mainline
+mode: ContinuousDelivery

readme.md

@@ -1,14 +1,33 @@
 [![Build status](https://ci.appveyor.com/api/projects/status/kbtxml9x2kcdgkju?svg=true)](https://ci.appveyor.com/project/OctopusDeploy/octo-exe)
 
-[Octopus Deploy][1] is an automated deployment server for professional .NET developers. 
+This repository contains the command line tool (`Octo.exe`) and .NET Client Library (`Octopus.Client`) for [Octopus Deploy][1], an automated deployment server for professional .NET developers. You can use them to create and deploy releases, create and push packages, and manage environments.
 
-**`Octo.exe`** is a command line tool for automating Octopus. You can use it to create and deploy releases, create and push packages, and manage environments.
+`Octo.exe` can be [downloaded from the Octopus downloads page][2], while `Octopus.Client` is [available on nuget.org][3]
 
-The tool can be [downloaded from the Octopus downloads page][2]. 
+## Documentation
+- [Octo.exe][4]
+- [Octopus.Client][5]
 
-Documentation can be found in the [Octopus Deploy documentation](http://docs.octopusdeploy.com/display/OD/Octo.exe+Command+Line). 
+## Issues
+Please see [Contributing](CONTRIBUTING.md)
 
-**Please raise and track issues for this project [here](https://github.com/OctopusDeploy/Issues/issues/).**
+## Compatibility
+For:
+- Octopus Server 3.0-3.2 use Octopus Client 3.0-3.2 (newer is better)
+- Octopus Server 3.3 use Octopus Client 3.3 or newer [release notes](https://octopus.com/downloads/3.3.0)
+- Octopus Server 3.4 use Octopus Client 3.4 or newer [release notes](https://octopus.com/downloads/3.4.0)
+
+## Versioning
+As of `3.5.0` we started using semantic versioning][6] for the client library, breaking away from the practice of syncing the version to Octopus Server.
+
+The [semantic versioning][6] applies to the command line interface of `Octo.exe` and the public api exposed by `Octopus.Client`. The `minor` version will be increased on feature additions, and `major` on breaking changes.
+
+## vNext
+As of Version 4, network operations in `Octopus.Client` will be `async`. We will continue to support version 3 for some time once version 4 is released, but may not add all new features.
 
 [1]: https://octopus.com
 [2]: https://octopus.com/downloads
+[3]: https://www.nuget.org/packages/Octopus.Client
+[4]: http://docs.octopusdeploy.com/display/OD/Octo.exe+Command+Line
+[5]: http://docs.octopusdeploy.com/display/OD/Octopus.Client
+[6]: http://semver.org/