Merge pull request #4 from jrperritt/master

penultimate additions (or so) from `rackspace/gophercloud`

CHANGELOG.md

@@ -1 +0,0 @@
-ExtractJSON method on gophercloud.Result

CONTRIBUTING.md

@@ -1,9 +1,9 @@
-# Contributing to gophercloud
+# Contributing to Gophercloud
 
 - [Getting started](#getting-started)
 - [Tests](#tests)
 - [Style guide](#basic-style-guide)
-- [5 ways to get involved](#5-ways-to-get-involved)
+- [3 ways to get involved](#5-ways-to-get-involved)
 
 ## Setting up your git workspace
 
@@ -97,6 +97,7 @@ import (
 
 	th "github.com/gophercloud/gophercloud/testhelper"
 	fake "github.com/gophercloud/gophercloud/testhelper/client"
+  "github.com/gophercloud/gophercloud/openstack/networking/v2/networks"
 )
 
 func TestGet(t *testing.T) {
@@ -131,7 +132,7 @@ func TestGet(t *testing.T) {
 	})
 
 	// Call our API operation
-	network, err := Get(fake.ServiceClient(), "d32019d3-bc6e-4319-9c1d-6722fc136a22").Extract()
+	network, err := networks.Get(fake.ServiceClient(), "d32019d3-bc6e-4319-9c1d-6722fc136a22").Extract()
 
 	// Assert no errors and equality
 	th.AssertNoErr(t, err)
@@ -182,15 +183,9 @@ cd ./path/to/package && go test -tags fixtures .
 
 ## Style guide
 
+See [here](/STYLEGUIDE.md)
 
-
-We follow the standard formatting recommendations and language idioms set out
-in the [Effective Go](https://golang.org/doc/effective_go.html) guide. It's
-definitely worth reading - but the relevant sections are
-[formatting](https://golang.org/doc/effective_go.html#formatting)
-and [names](https://golang.org/doc/effective_go.html#names).
-
-## 5 ways to get involved
+## 3 ways to get involved
 
 There are five main ways you can get involved in our open-source project, and
 each is described briefly below. Once you've made up your mind and decided on
@@ -201,23 +196,7 @@ required to adhere to:
 2. checkout a [new branch](https://github.com/Kunena/Kunena-Forum/wiki/Create-a-new-branch-with-git-and-manage-branches)
 3. submit your branch as a [pull request](https://help.github.com/articles/creating-a-pull-request/)
 
-### 1. Providing feedback
-
-On of the easiest ways to get readily involved in our project is to let us know
-about your experiences using our SDK. Feedback like this is incredibly useful
-to us, because it allows us to refine and change features based on what our
-users want and expect of us. There are a bunch of ways to get in contact! You
-can [ping us](https://developer.rackspace.com/support/) via e-mail, talk to us on irc
-(#rackspace-dev on freenode), [tweet us](https://twitter.com/rackspace), or
-submit an issue on our [bug tracker](/issues). Things you might like to tell us
-are:
-
-* how easy was it to start using our SDK?
-* did it meet your expectations? If not, why not?
-* did our documentation help or hinder you?
-* what could we improve in general?
-
-### 2. Fixing bugs
+### 1. Fixing bugs
 
 If you want to start fixing open bugs, we'd really appreciate that! Bug fixing
 is central to any project. The best way to get started is by heading to our
@@ -226,41 +205,16 @@ bugs that you think nobody is working on. It might be useful to comment on the
 thread to see the current state of the issue and if anybody has made any
 breakthroughs on it so far.
 
-### 3. Improving documentation
-
-We have three forms of documentation:
-
-* short README documents that briefly introduce a topic
-* reference documentation on [godoc.org](http://godoc.org) that is automatically
-generated from source code comments
-* user documentation on our [homepage](http://gophercloud.io) that includes
-getting started guides, installation guides and code samples
+### 2. Improving documentation
+The best source of documentation is on [godoc.org](http://godoc.org). It is
+automatically generated from the source code.
 
 If you feel that a certain section could be improved - whether it's to clarify
 ambiguity, correct a technical mistake, or to fix a grammatical error - please
 feel entitled to do so! We welcome doc pull requests with the same childlike
 enthusiasm as any other contribution!
 
-### 4. Optimizing existing features
-
-If you would like to improve or optimize an existing feature, please be aware
-that we adhere to [semantic versioning](http://semver.org) - which means that
-we cannot introduce breaking changes to the API without a major version change
-(v1.x -> v2.x). Making that leap is a big step, so we encourage contributors to
-refactor rather than rewrite. Running tests will prevent regression and avoid
-the possibility of breaking somebody's current implementation.
-
-Another tip is to keep the focus of your work as small as possible - try not to
-introduce a change that affects lots and lots of files because it introduces
-added risk and increases the cognitive load on the reviewers checking your
-work. Change-sets which are easily understood and will not negatively impact
-users are more likely to be integrated quickly.
-
-Lastly, if you're seeking to optimize a particular operation, you should try to
-demonstrate a negative performance impact - perhaps using Go's inbuilt
-[benchmark capabilities](http://dave.cheney.net/2013/06/30/how-to-write-benchmarks-in-go).
-
-### 5. Working on a new feature
+###3. Working on a new feature
 
 If you've found something we've left out, definitely feel free to start work on
 introducing that feature. It's always useful to open an issue or submit a pull

README.md

@@ -1,4 +1,3 @@
-# WARNING: CURRENTLY NOT SUITABLE FOR CONSUMPTION. API IN FLUX.
 # Gophercloud: an OpenStack SDK for Go
 [![Build Status](https://travis-ci.org/gophercloud/gophercloud.svg?branch=master)](https://travis-ci.org/gophercloud/gophercloud)
 [![Coverage Status](https://coveralls.io/repos/github/gophercloud/gophercloud/badge.svg?branch=master)](https://coveralls.io/github/gophercloud/gophercloud?branch=master)
@@ -126,27 +125,15 @@ The above code sample creates a new server with the parameters, and embodies the
 new resource in the `server` variable (a
 [`servers.Server`](http://godoc.org/github.com/gophercloud/gophercloud) struct).
 
-### Next steps
+## Backwards-Compatibility Guarantees
 
-Cool! You've handled authentication, got your `ProviderClient` and provisioned
-a new server. You're now ready to use more OpenStack services.
-
-* [Getting started with Compute](http://gophercloud.io/docs/compute)
-* [Getting started with Object Storage](http://gophercloud.io/docs/object-storage)
-* [Getting started with Networking](http://gophercloud.io/docs/networking)
-* [Getting started with Block Storage](http://gophercloud.io/docs/block-storage)
-* [Getting started with Identity](http://gophercloud.io/docs/identity)
+None. Vendor it and write tests covering the parts you use.
 
 ## Contributing
 
-Engaging the community and lowering barriers for contributors is something we
-care a lot about. For this reason, we've taken the time to write a [contributing
-guide](./CONTRIBUTING.md) for folks interested in getting involved in our project.
-If you're not sure how you can get involved, feel free to submit an issue or
-[contact us](https://developer.rackspace.com/support/). You don't need to be a
-Go expert - all members of the community are welcome!
+See the [contributing guide](./CONTRIBUTING.md).
 
 ## Help and feedback
 
 If you're struggling with something or have spotted a potential bug, feel free
-to submit an issue to our [bug tracker](/issues) or [contact us directly](https://developer.rackspace.com/support/).
+to submit an issue to our [bug tracker](/issues).

STYLEGUIDE.md

@@ -0,0 +1,39 @@
+
+## On Pull Requests
+
+- Before you start a PR there needs to be a Github issue and a discussion about it
+  on that issue with a core contributor, even if it's just a 'SGTM'.
+
+- A PR's description must reference the issue it closes with a `For <ISSUE NUMBER>` (e.g. For #293).
+
+- A PR's description must contain link(s) to the line(s) in the OpenStack
+  source code (on Github) that prove(s) the PR code to be valid. Links to documentation
+  are not good enough. The link(s) should be to a non-`master` branch. For example,
+  a pull request implementing the creation of a Neutron v2 subnet might put the
+  following link in the description:
+  https://github.com/openstack/neutron/blob/stable/mitaka/neutron/api/v2/attributes.py#L749
+  From that link, a reviewer (or user) can verify the fields in the request/response
+  objects in the PR.
+
+- A PR that is in-progress should have `[wip]` in front of the PR's title. When
+  ready for review, remove the `[wip]` and ping a core contributor with an `@`.
+
+- A PR should be small. Even if you intend on implementing an entire
+  service, a PR should only be one route of that service
+  (e.g. create server or get server, but not both).
+
+- Unless explicitly asked, do not squash commits in the middle of a review; only
+  append. It makes it difficult for the reviewer to see what's changed from one
+  review to the next.
+
+## On Code
+
+- In re design: follow as closely as is reasonable the code already in the library.
+  Most operations (e.g. create, delete) admit the same design.
+
+- Unit tests and acceptance (integration) tests must be written to cover each PR.
+  Tests for operations with several options (e.g. list, create) should include all
+  the options in the tests. This will allow users to verify an operation on their
+  own infrastructure and see an example of usage.
+
+- If in doubt, ask in-line on the PR.