corl 0.5.6 → 0.5.7

data/README.rdoc

@@ -1,592 +1,200 @@
-# CORL - Coral Orchestration and Research Library
+= CORL - Coral Orchestration and Research Library
 
-[Nucleon](https://github.com/coralnexus/nucleon) plugin library and framework for building, synchronizing, and executing 
-distributed actions and agents across heterogenous networks.
 
-[Nucleon](https://github.com/coralnexus/nucleon) powered 
+{Nucleon}[https://github.com/coralnexus/nucleon] plugin library and framework 
+for building, synchronizing, and executing distributed actions and agents 
+across heterogeneous networks of machines.
 
 
+== Origin and philosophy  (aka: Why is this project being developed?)
 
 
+This project began with the need to automate the management of our own 
+infrastructure architecture starting in mid 2012.  In early 2013 the initial 
+work towards this goal was merged into two projects; Nucleon (general plugin 
+management framework and execution environment), and CORL (this project).
 
+We believe in the future, as machines become more connected and integrated,
+there will be profound need for frameworks that allow for the creation of semi
+or fully autonomous cyber entities that evolve across the cloud. These software 
+entities will have varying capabilities and objectives but all will be capable 
+of managing their machines, communicating with others in their network, and 
+reproducing when neccessary.  We want to help further a new era of smart 
+infrastructure by providing an open source framework for developing such 
+entities and their requisite environments.
 
+Treating machines as autonomous software entities that can self manage allows
+for the agile and adaptive evolution of the computer systems we rely on to make
+our lives easier.  Management dashboards and user controls are great but the 
+future of the web belongs to the machines acting in our interests.  CORL is
+being developed to help bring the machines to life (in a manner of speaking).
 
 
+== State of the project
 
 
+CORL, and its parent {Nucleon}[https://github.com/coralnexus/nucleon]
+are still in alpha development and not yet ready for production unless you know 
+how to develop with it and fix bugs.  We use it for our infrastructure 
+architecture internally, but there are kinks we still have to work out to meet 
+the full set of intended architectual objectives.  We are currently finalizing 
+the acquarium, next comes the fish.
 
+If you are a tinkerer and are passionate about machine managed systems or 
+organically inspired software systems we invite your contributions in whatever
+form you wish to provide.  Contact Adrian Webb ( adrian.webb@coralnexus.com ) 
+with questions or feedback or just post an issue.
 
+<b>Note that all development and testing has been on Ubuntu (12.04/14.04) so 
+far.</b>
 
+To review tasks needing completion before first production release, {see the TODO}[link:info/TODO.rdoc].
 
+To get an overview of what plugins are currently provided, go {here}[link:info/PLUGINS.rdoc].
 
-![Logo][logo]
-[logo]: http://cl.ly/image/3Y013H0A2z3z/gundam-ruby.png
 
-Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
-[major version][semver].
+== CORL architecture
 
-## Philosophy
 
-API wrappers [should reflect the idioms of the language in which they were
-written][wrappers]. Octokit.rb wraps the [GitHub API][github-api] in a flat API
-client that follows Ruby conventions and requires little knowledge of REST.
-Most methods have positional arguments for required input and an options hash
-for optional parameters, headers, or other options:
+CORL is a <b>programming framework</b> and <b>execution environment</b> intended for:
 
-```ruby
-# Fetch a README with Accept header for HTML format
-Octokit.readme 'al3x/sovereign', :accept => 'application/vnd.github.html'
-```
+  1. Management of reusable high availability platforms across cloud providers 
+  
+  2. Distributed programming or script execution across dynamically managed nodes
+  
+  3. Decentralized networking and provisioning of heterogeneous machines
+  
+  4. Cloud based evolutionary multi-agent simulations and processing
 
 
-[wrappers]: http://wynnnetherland.com/journal/what-makes-a-good-api-wrapper
-[github-api]: http://developer.github.com
+=== Key design requirements:
 
-## Quick start
 
-Install via Rubygems
+* Lightweight programming framework for executing actions and managing agents
+  across dynamically evolving networks of nodes
+* Pluggable data driven integration capabilities
+* Portable actions and packages that can be searched and aggregated from across
+  the system
+* Network projects that connect nodes, architecture, and resources as 
+  decentralized revision controlled projects, not centralized hosted databases
+* CLI action interface
+* REST action host (not implemented yet)
 
-    gem install octokit
 
-... or add to your Gemfile
+=== Things CORL is NOT meant to be:
 
-    gem "octokit", "~> 3.0"
 
-### Making requests
+* A dashboard or UI driven application (we are focused solely on machines)
+* A continuously running agent or hosted application 
+  (we need to minimize system resource usage)
+* A bloated platform that requires a multi-system platform or dedicated 
+  servers to operate
+* A virtualization system (although it uses them)
 
-[API methods][] are available as module methods (consuming module-level
-configuration) or as client instance methods.
+Care to {walk through the CORL architecture on Prezi}[https://prezi.com/enwlxtfhdqoq/corl]?
 
-```ruby
-# Provide authentication credentials
-Octokit.configure do |c|
-  c.login = 'defunkt'
-  c.password = 'c0d3b4ssssss!'
-end
 
-# Fetch the current user
-Octokit.user
-```
-or
+== CORL focus areas
 
-```ruby
-# Provide authentication credentials
-client = Octokit::Client.new(:login => 'defunkt', :password => 'c0d3b4ssssss!')
-# Fetch the current user
-client.user
-```
 
-[API methods]: http://octokit.github.io/octokit.rb/method_list.html
+Our ultimate goal is the scalable application of our resources, time, and 
+workflows, while allowing for evolutionary and adaptive growth of our IT 
+infrastructure.
 
-### Consuming resources
+{<img src="https://raw.githubusercontent.com/coralnexus/corl/0.5/images/purpose.png" align="right">}[link:README.rdoc]
 
-Most methods return a `Resource` object which provides dot notation and `[]`
-access for fields returned in the API response.
+<b>Packaging</b> serves as a foundation for an automated architecture by
+providing reusable configuration managed images that can be easily launched
+across local and remote virtual machine and container providers.  Our goal with
+packaging is to turn machines into programmable data objects which can be easily
+automated through diverse software systems.
 
-```ruby
-# Fetch a user
-user = Octokit.user 'jbarnette'
-puts user.name
-# => "John Barnette"
-puts user.fields
-# => <Set: {:login, :id, :gravatar_id, :type, :name, :company, :blog, :location, :email, :hireable, :bio, :public_repos, :followers, :following, :created_at, :updated_at, :public_gists}>
-puts user[:company]
-# => "GitHub"
-user.rels[:gists].href
-# => "https://api.github.com/users/jbarnette/gists"
-```
+<b>Automation</b> builds on packaged data and systems, and allows for reusable 
+development of flexible integrated workflows.  Automation capabilities depend
+on the degree to which machine inspection and management has been abstracted 
+from the various configuration files, system services, and operating system 
+nuances.  CORL tries to bridge technologies that abstract the relevant data
+from the machine and various applications so we can more easily monitor and 
+automate.  Two modes of automation are possible; actions (fire and forget), and
+agents (managed services that utilize actions).
 
-**Note:** URL fields are culled into a separate `.rels` collection for easier
-[Hypermedia](#hypermedia-agent) support.
+<b>Scaling</b> of infrastructure resources and workflows becomes easier when we 
+have a flexible automation system that can work with machines as data, and 
+deeply integrate with the software, services, and workflows we already employ.
 
-### Accessing HTTP responses
 
-While most methods return a `Resource` object or a Boolean, sometimes you may
-need access to the raw HTTP response headers. You can access the last HTTP
-response with `Client#last_response`:
+=== Packaging system
 
-```ruby
-user      = Octokit.user 'andrewpthorp'
-response  = Octokit.last_response
-etag      = response.headers[:etag]
-```
 
-## Authentication
+To build adaptive infrastructure we treat each machine as a programmable data 
+model that is connected to other machines in a shared network (data pool).  
+This also helps create an entirely hands off administration process that is easy
+to query and modify through remote action execution.
 
-Octokit supports the various [authentication methods supported by the GitHub
-API][auth]:
+https://raw.githubusercontent.com/coralnexus/corl/0.5/images/packaging-overview.png
 
-### Basic Authentication
+To read more on the CORL packaging system, {see the packaging overview}[link:info/PACKAGING.rdoc].
 
-Using your GitHub username and password is the easiest way to get started
-making authenticated requests:
 
-```ruby
-client = Octokit::Client.new \
-  :login    => 'defunkt',
-  :password => 'c0d3b4ssssss!'
+=== Automation system
 
-user = client.user
-user.login
-# => "defunkt"
-```
-While Basic Authentication allows you to get started quickly, OAuth access
-tokens are the preferred way to authenticate on behalf of users.
 
-### OAuth access tokens
+The ability to create, reuse, and extend integrated development and 
+administration workflows across standardized plugin interfaces gives us the 
+ability to focus on the task at hand while allowing for the creation of 
+different interface implementations when needed.
 
-[OAuth access tokens][oauth] provide two main benefits over using your username
-and password:
 
-* **Revokable access**. Access tokens can be revoked, removing access for only
-  that token without having to change your password everywhere.
-* **Limited access**. Access tokens have [access scopes][] which allow for more
-  granular access to API resources. For instance, you can grant a third party
-  access to your gists but not your private repositories.
+https://raw.githubusercontent.com/coralnexus/corl/0.5/images/automation-overview.png
 
-To use an access token with the Octokit client, pass your token in the
-`:access_token` options parameter in lieu of your username and password:
 
-```ruby
-client = Octokit::Client.new(:access_token => "<your 40 char token>")
+== CORL installation and setup
 
-user = client.user
-user.login
-# => "defunkt"
-```
-
-You can [create access tokens through your GitHub Account Settings](https://help.github.com/articles/creating-an-access-token-for-command-line-use)
-or with a basic authenticated Octokit client:
-
-```ruby
-client = Octokit::Client.new \
-  :login    => 'defunkt',
-  :password => 'c0d3b4ssssss!'
+CORL is designed so it requires few dependencies outside of the Ruby language
+and some useful Gems.
 
-client.create_authorization(:scopes => ["user"], :note => "Name of token")
-# => <your new oauth token>
-```
+See the {installation instructions}[link:info/INSTALLATION.rdoc] for information on requirements and getting
+CORL installed on your machines.
 
-### Two-Factor Authentication
 
-[Two-Factor Authentication](https://help.github.com/articles/about-two-factor-authentication) brings added security to the account by requiring more information to login.
 
-Using two-factor authentication for API calls is as simple as adding the [required header](http://developer.github.com/v3/auth/#working-with-two-factor-authentication) as an option:
+== Ruby Versions
 
-```ruby
-client = Octokit::Client.new \
-  :login    => 'defunkt',
-  :password => 'c0d3b4ssssss!'
 
-user = client.user("defunkt", :headers => { "X-GitHub-OTP" => "<your 2FA token>" })
-```
+This library has been developed with and should support MRI Ruby versions:
 
-As you can imagine, this gets annoying quick since two-factor auth tokens are very short lived. So it is recommended to create an oauth token for the user to communicate with the API:
-
-```ruby
-client = Octokit::Client.new \
-  :login    => 'defunkt',
-  :password => 'c0d3b4ssssss!'
-
-client.create_authorization(:scopes => ["user"], :note => "Name of token",
-                            :headers => { "X-GitHub-OTP" => "<your 2FA token>" })
-# => <your new oauth token>
-```
-
-### Using a .netrc file
-
-Octokit supports reading credentials from a netrc file (defaulting to
-`~/.netrc`).  Given these lines in your netrc:
-
-```
-machine api.github.com
-  login defunkt
-  password c0d3b4ssssss!
-```
-You can now create a client with those credentials:
-
-```ruby
-client = Octokit::Client.new(:netrc => true)
-client.login
-# => "defunkt"
-```
-But _I want to use OAuth_ you say. Since the GitHub API supports using an OAuth
-token as a Basic password, you totally can:
-
-```
-machine api.github.com
-  login defunkt
-  password <your 40 char token>
-```
-
-**Note:** Support for netrc requires adding the [netrc gem][] to your Gemfile
-or `.gemspec`.
-
-### Application authentication
-
-Octokit also supports application-only authentication [using OAuth application client
-credentials][app-creds]. Using application credentials will result in making
-anonymous API calls on behalf of an application in order to take advantage of
-the higher rate limit.
-
-```ruby
-client = Octokit::Client.new \
-  :client_id     => "<your 20 char id>",
-  :client_secret => "<your 40 char secret>"
-
-user = client.user 'defunkt'
-```
-
-[auth]: http://developer.github.com/v3/#authentication
-[oauth]: http://developer.github.com/v3/oauth/
-[access scopes]: http://developer.github.com/v3/oauth/#scopes
-[app-creds]: http://developer.github.com/v3/#increasing-the-unauthenticated-rate-limit-for-oauth-applications
-
-## Pagination
-
-Many GitHub API resources are [paginated][]. While you may be tempted to start
-adding `:page` parameters to your calls, the API returns links to the next,
-previous, and last pages for you in the `Link` response header as [Hypermedia
-link relations](#hypermedia-agent).
-
-```ruby
-issues = Octokit.issues 'rails/rails', :per_page => 100
-issues.concat Octokit.last_response.rels[:next].get.data
-```
-
-### Auto pagination
-
-For smallish resource lists, Octokit provides auto pagination. When this is
-enabled, calls for paginated resources will fetch and concatenate the results
-from every page into a single array:
-
-```ruby
-Octokit.auto_paginate = true
-issues = Octokit.issues 'rails/rails'
-issues.length
-
-# => 702
-```
-
-**Note:** While Octokit auto pagination will set the page size to the maximum
-`100`, and seek to not overstep your rate limit, you probably want to use a
-custom pattern for traversing large lists.
-
-[paginated]: http://developer.github.com/v3/#pagination
-
-## Configuration and defaults
-
-While `Octokit::Client` accepts a range of options when creating a new client
-instance, Octokit's configuration API allows you to set your configuration
-options at the module level. This is particularly handy if you're creating a
-number of client instances based on some shared defaults.
-
-### Configuring module defaults
-
-Every writable attribute in {Octokit::Configurable} can be set one at a time:
-
-```ruby
-Octokit.api_endpoint = 'http://api.github.dev'
-Octokit.web_endpoint = 'http://github.dev'
-```
-
-or in batch:
-
-```ruby
-Octokit.configure do |c|
-  c.api_endpoint = 'http://api.github.dev'
-  c.web_endpoint = 'http://github.dev'
-end
-```
-
-### Using ENV variables
-
-Default configuration values are specified in {Octokit::Default}. Many
-attributes will look for a default value from the ENV before returning
-Octokit's default.
-
-```ruby
-# Given $OCTOKIT_API_ENDPOINT is "http://api.github.dev"
-Octokit.api_endpoint
-
-# => "http://api.github.dev"
-```
-
-Deprecation warnings and API endpoints in development preview warnings are
-printed to STDOUT by default, these can be disabled by setting the ENV
-`OCTOKIT_SILENT=true`.
-
-## Hypermedia agent
-
-Starting in version 2.0, Octokit is [hypermedia][]-enabled. Under the hood,
-{Octokit::Client} uses [Sawyer][], a hypermedia client built on [Faraday][].
-
-### Hypermedia in Octokit
-
-Resources returned by Octokit methods contain not only data but hypermedia
-link relations:
-
-```ruby
-user = Octokit.user 'technoweenie'
-
-# Get the repos rel, returned from the API
-# as repos_url in the resource
-user.rels[:repos].href
-# => "https://api.github.com/users/technoweenie/repos"
-
-repos = user.rels[:repos].get.data
-repos.last.name
-# => "faraday-zeromq"
-```
-
-When processing API responses, all `*_url` attributes are culled in to the link
-relations collection. Any `url` attribute becomes `.rels[:self]`.
-
-### URI templates
-
-You might notice many link relations have variable placeholders. Octokit
-supports [URI Templates][uri-templates] for parameterized URI expansion:
-
-```ruby
-repo = Octokit.repo 'pengwynn/pingwynn'
-rel = repo.rels[:issues]
-# => #<Sawyer::Relation: issues: get https://api.github.com/repos/pengwynn/pingwynn/issues{/number}>
-
-# Get a page of issues
-rel.get.data
-
-# Get issue #2
-rel.get(:uri => {:number => 2}).data
-```
-
-### The Full Hypermedia Experience™
-
-If you want to use Octokit as a pure hypermedia API client, you can start at
-the API root and follow link relations from there:
-
-```ruby
-root = Octokit.root
-root.rels[:repository].get :uri => {:owner => "octokit", :repo => "octokit.rb" }
-```
-
-Octokit 3.0 aims to be hypermedia-driven, removing the internal URL
-construction currently used throughout the client.
-
-[hypermedia]: http://en.wikipedia.org/wiki/Hypermedia
-[Sawyer]: https://github.com/lostisland/sawyer
-[Faraday]: https://github.com/lostisland/faraday
-[uri-templates]: http://tools.ietf.org/html/rfc6570
-
-## Upgrading guide
-
-Version 3.0 includes a couple breaking changes when upgrading from v2.x.x:
-
-The [default media type][default-media-type] is now `v3` instead of `beta`. If
-you need to request the older media type, you can set the default media type
-for the client:
-
-```ruby
-Octokit.default_media_type = "application/vnd.github.beta+json"
-```
-or per-request
-
-```ruby
-Octokit.emails(:accept => "application/vnd.github.beta+json")
-```
-
-The long-deprecated `Octokit::Client#create_download` method has been removed.
-
-[default-media-type]: https://developer.github.com/changes/2014-01-07-upcoming-change-to-default-media-type/
-
-### Upgrading from 1.x.x
-
-Version 2.0 includes a completely rewritten `Client` factory that now memoizes
-client instances based on unique configuration options. Breaking changes also
-include:
-
-* `:oauth_token` is now `:access_token`
-* `:auto_traversal` is now `:auto_paginate`
-* `Hashie::Mash` has been removed. Responses now return a `Sawyer::Resource`
-  object. This new type behaves mostly like a Ruby `Hash`, but does not fully
-  support the `Hashie::Mash` API.
-* Two new client error types are raised where appropriate:
-  `Octokit::TooManyRequests` and `Octokit::TooManyLoginAttempts`
-* The `search_*` methods from v1.x are now found at `legacy_search_*`
-* Support for netrc requires including the [netrc gem][] in your Gemfile or
-  gemspec.
-* DateTime fields are now proper `DateTime` objects. Previous versions outputted DateTime fields as 'String' objects.
-
-[netrc gem]: https://rubygems.org/gems/netrc
-
-
-## Advanced usage
-
-Since Octokit employs [Faraday][faraday] under the hood, some behavior can be
-extended via middleware.
-
-### Debugging
-
-Often, it helps to know what Octokit is doing under the hood. You can add a
-logger to the middleware that enables you to peek into the underlying HTTP
-traffic:
-
-```ruby
-stack = Faraday::RackBuilder.new do |builder|
-  builder.response :logger
-  builder.use Octokit::Response::RaiseError
-  builder.adapter Faraday.default_adapter
-end
-Octokit.middleware = stack
-Octokit.user 'pengwynn'
-```
-```
-I, [2013-08-22T15:54:38.583300 #88227]  INFO -- : get https://api.github.com/users/pengwynn
-D, [2013-08-22T15:54:38.583401 #88227] DEBUG -- request: Accept: "application/vnd.github.beta+json"
-User-Agent: "Octokit Ruby Gem 2.0.0.rc4"
-I, [2013-08-22T15:54:38.843313 #88227]  INFO -- Status: 200
-D, [2013-08-22T15:54:38.843459 #88227] DEBUG -- response: server: "GitHub.com"
-date: "Thu, 22 Aug 2013 20:54:40 GMT"
-content-type: "application/json; charset=utf-8"
-transfer-encoding: "chunked"
-connection: "close"
-status: "200 OK"
-x-ratelimit-limit: "60"
-x-ratelimit-remaining: "39"
-x-ratelimit-reset: "1377205443"
-...
-```
-
-See the [Faraday README][faraday] for more middleware magic.
-
-### Caching
-
-If you want to boost performance, stretch your API rate limit, or avoid paying
-the hypermedia tax, you can use [Faraday Http Cache][cache].
-
-Add the gem to your Gemfile
-
-    gem 'faraday-http-cache'
-
-Next, construct your own Faraday middleware:
-
-```ruby
-stack = Faraday::RackBuilder.new do |builder|
-  builder.use Faraday::HttpCache
-  builder.use Octokit::Response::RaiseError
-  builder.adapter Faraday.default_adapter
-end
-Octokit.middleware = stack
-```
-
-Once configured, the middleware will store responses in cache based on ETag
-fingerprint and serve those back up for future `304` responses for the same
-resource. See the [project README][cache] for advanced usage.
-
-
-[cache]: https://github.com/plataformatec/faraday-http-cache
-[faraday]: https://github.com/lostisland/faraday
-
-## Hacking on Octokit.rb
-
-If you want to hack on Octokit locally, we try to make [bootstrapping the
-project][bootstrapping] as painless as possible. To start hacking, clone and run:
-
-    script/bootstrap
-
-This will install project dependencies and get you up and running. If you want
-to run a Ruby console to poke on Octokit, you can crank one up with:
-
-    script/console
-
-Using the scripts in `./scripts` instead of `bundle exec rspec`, `bundle
-console`, etc.  ensures your dependencies are up-to-date.
-
-### Running and writing new tests
-
-Octokit uses [VCR][] for recording and playing back API fixtures during test
-runs. These cassettes (fixtures) are part of the Git project in the `spec/cassettes`
-folder. If you're not recording new cassettes you can run the specs with existing
-cassettes with:
-
-    script/test
-
-Octokit uses environmental variables for storing credentials used in testing.
-If you are testing an API endpoint that doesn't require authentication, you
-can get away without any additional configuration. For the most part, tests
-use an authenticated client, using a token stored in `ENV['OCTOKIT_TEST_GITHUB_TOKEN']`.
-There are several different authenticating method's used across the api.
-Here is the full list of configurable environmental variables for testing
-Octokit:
-
-ENV Variable | Description |
-:-------------------|:-----------------|
-`OCTOKIT_TEST_GITHUB_LOGIN`| GitHub login name (preferably one created specifically for testing against).
-`OCTOKIT_TEST_GITHUB_PASSWORD`| Password for the test GitHub login.
-`OCTOKIT_TEST_GITHUB_TOKEN` | [Personal Access Token](https://github.com/blog/1509-personal-api-tokens) for the test GitHub login.
-`OCTOKIT_TEST_GITHUB_CLIENT_ID` | Test OAuth application client id.
-`OCTOKIT_TEST_GITHUB_CLIENT_SECRET` | Test OAuth application client secret.
-`OCTOKIT_TEST_GITHUB_REPOSITORY` | Test repository to perform destructive actions against, this should not be set to any repository of importance. **Automatically created by the test suite if nonexistent** Default: `api-sandbox`
-`OCTOKIT_TEST_GITHUB_ORGANIZATION` | Test organization.
-
-Since we periodically refresh our cassettes, please keep some points in mind
-when writing new specs.
-
-* **Specs should be idempotent**. The HTTP calls made during a spec should be
-  able to be run over and over. This means deleting a known resource prior to
-  creating it if the name has to be unique.
-* **Specs should be able to be run in random order.** If a spec depends on
-  another resource as a fixture, make sure that's created in the scope of the
-  spec and not depend on a previous spec to create the data needed.
-* **Do not depend on authenticated user info.** Instead of asserting
-  actual values in resources, try to assert the existence of a key or that a
-  response is an Array. We're testing the client, not the API.
-
-[bootstrapping]: http://wynnnetherland.com/linked/2013012801/bootstrapping-consistency
-[VCR]: https://github.com/vcr/vcr
-
-## Supported Ruby Versions
-
-This library aims to support and is [tested against][travis] the following Ruby
-implementations:
-
-* Ruby 1.9.2
-* Ruby 1.9.3
-* Ruby 2.0.0
-* Ruby 2.1.0
+* <b>Ruby 1.9.2</b>
+* <b>Ruby 1.9.3</b>
+* <b>Ruby 2.0.0</b>
+* <b>Ruby 2.1.0</b>
 
 If something doesn't work on one of these Ruby versions, it's a bug.
 
 This library may inadvertently work (or seem to work) on other Ruby
 implementations, but support will only be provided for the versions listed
-above.
+above.  *Rubinius* is being tested and will ultimately be supported.
+
+This library currently does not work on *JRuby* due to CORL gem dependencies, 
+such as Rugged, that provide C Ruby extensions (which JRuby does not support).
+
+We have developed this so far pretty much entirely on Ubuntu but the core 
+framework should work with other Linux distributions.  There are known issues
+with Windows when executed through Vagrant and Cygwin.
 
-If you would like this library to support another Ruby version, you may
-volunteer to be a maintainer. Being a maintainer entails making sure all tests
-run and pass on that implementation. When something breaks on your
-implementation, you will be responsible for providing patches in a timely
-fashion. If critical issues for a particular implementation exist at the time
-of a major release, support for that Ruby version may be dropped.
 
-[travis]: https://travis-ci.org/octokit/octokit.rb
+== Versioning
 
-## Versioning
 
-This library aims to adhere to [Semantic Versioning 2.0.0][semver]. Violations
-of this scheme should be reported as bugs. Specifically, if a minor or patch
-version is released that breaks backward compatibility, that version should be
-immediately yanked and/or a new version should be immediately released that
-restores compatibility. Breaking changes to the public API will only be
-introduced with new major versions. As a result of this policy, you can (and
-should) specify a dependency on this gem using the [Pessimistic Version
-Constraint][pvc] with two digits of precision. For example:
+This framework should be considered unstable and likely to break as remaining
+bugs and unit testing are completed going forward.  When we reach version 1.0.0 
+full {semantic versioning}[http://semver.org] will be ahered to. Until then
+the minor version specifies a major architectural change, and patch versions
+could fix bugs and revise features that could break backward compatibility.
 
-    spec.add_dependency 'octokit', '~> 3.0'
 
-[semver]: http://semver.org/
-[pvc]: http://guides.rubygems.org/patterns/#pessimistic-version-constraint
+== License
 
-## License
 
 Licensed under Apache License 2.0. See LICENSE.txt for further details.
 
-Copyright © 2013-2014 Adrian Webb <adrian.webb@coralnexus.com> Coral Technology Group LLC
+Copyright © 2013-2015 Adrian Webb ( mailto:adrian.webb@coraltech.net ) <b>Coral Technology Group LLC</b>