Merge pull request #226 from jamiehannaford/new-readme
Updated README
diff --git a/README.asciidoc b/README.asciidoc
deleted file mode 100644
index ebffbdb..0000000
--- a/README.asciidoc
+++ /dev/null
@@ -1,74 +0,0 @@
-== Gophercloud -- V0.2.0 image:https://secure.travis-ci.org/rackspace/gophercloud.png?branch=v0.2.0["build status",link="https://travis-ci.org/rackspace/gophercloud"]
-
-Gophercloud currently lets you authenticate with OpenStack providers to create and manage servers (compute service) and objects (object-storage service).
-We are working on extending the API to further include block storage, DNS, databases, security groups, and other features.
-
-WARNING: This library is still in the very early stages of development. Unless you want to contribute, it probably isn't what you want. Yet.
-
-=== Outstanding Features
-
-1. Apache 2.0 License, making Gophercloud friendly to commercial and open-source enterprises alike.
-2. Gophercloud is one of the most actively maintained Go SDKs for OpenStack.
-3. Gophercloud supports Identity V2, Nova V2, and Object Storage V1 APIs. More coming soon!
-5. Gophercloud supports automatic reauthentication upon auth token timeout, if enabled by your software.
-6. Gophercloud is the only SDK implementation with actual acceptance-level integration tests.
-
-=== Dependencies
-* Go 1.* (For information on installing Go and setting up your environment, go link:https://golang.org/doc/install[here])
-* git
-
-=== Getting the code
-
-To download Gophercloud, simply run
-```
-go get github.com/rackspace/gophercloud
-```
-It will automatically retrieve all dependencies. Goperhcloud and its dependencies will be located within your $GOPATH (%GOPATH% if you are using Windows).
-
-=== Running the tests
-
-Gophercloud has both unit tests and acceptance (integration) tests.
-
-To run the unit tests, run
-```
-go test -v github.com/rackspace/gophercloud
-```
-from the Gophercloud root directory.
-
-To run the acceptance tests, run
-```
-go test -v -tags acceptance github.com/rackspace/gophercloud
-```
-*Note: Running the acceptance tests briefly creates (and deletes) real resources. You may incur costs from your provider by running these.*
-
-To run specific tests, use a regular expression with the `run` flag. For example, to just run the authentication test (named TestAuthentication), run
-```
-go test -v -run "Authentication" -tags acceptance github.com/rackspace/gophercloud
-```
-
-=== What Does it Look Like?
-
-The Gophercloud 0.1.0 and earlier APIs are now deprecated and obsolete.
-No new feature development will occur for 0.1.0 or 0.0.0.
-However, we will accept and provide bug fixes for these APIs.
-Please refer to the acceptance tests in the master brach for code examples using the v0.1.0 API.
-The most up to date documentation for version 0.1.x can be found at link:http://godoc.org/github.com/rackspace/gophercloud[our Godoc.org documentation].
-
-We are working on a new API that provides much better support for extensions, pagination, and other features that proved difficult to implement before.
-This new API will be substantially more Go-idiomatic as well; one of the complaints received about 0.1.x and earlier is that it didn't "feel" right.
-To see what this new API is going to look like, you can look at the code examples up on the link:http://gophercloud.io/docs.html[Gophercloud website].
-If you're interested in tracking progress, note that features for version 0.2.0 will appear in the `v0.2.0` branch until merged to master.
-
-=== How can I Contribute?
-
-After using Gophercloud for a while, you might find that it lacks some useful feature, or that existing behavior seems buggy. We welcome contributions from our users for both missing functionality as well as for bug fixes. We encourage contributors to collaborate with the link:http://gophercloud.io/community.html[Gophercloud community.]
-
-Finally, Gophercloud maintains its own link:http://gophercloud.io[announcements and updates blog.]
-Feel free to check back now and again to see what's new.
-
-== License
-
-Copyright (C) 2013, 2014 Rackspace, Inc.
-
-Licensed under the Apache License, Version 2.0
-
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..74a4cd4
--- /dev/null
+++ b/README.md
@@ -0,0 +1,154 @@
+# gophercloud: the OpenStack SDK for Go
+[](https://travis-ci.org/rackspace/gophercloud)
+
+gophercloud is a flexible SDK that allows you to consume and work with OpenStack
+clouds in a simple and idiomatic way using golang. Many services are supported,
+including Compute, Block Storage, Object Storage, Networking, and Identity.
+Each service API is backed with getting started guides, code samples, reference
+documentation, unit tests and acceptance tests.
+
+## Useful links
+
+* [gophercloud homepage](http://gophercloud.io)
+* [Reference documentation](http://godoc.org/github.com/rackspace/gophercloud)
+* [Getting started guides](http://gophercloud.io/docs)
+* [Effective Go](https://golang.org/doc/effective_go.html)
+
+## How to install
+
+Before installing, you need to ensure that your [GOPATH environment variable](https://golang.org/doc/code.html#GOPATH)
+is pointing to an appropriate directory where you want to install gophercloud:
+
+```bash
+mkdir $HOME/go
+export GOPATH=$HOME/go
+```
+
+Once this is set up, you can install the gophercloud package like so:
+
+```bash
+go get github.com/rackspace/gophercloud
+```
+
+This will install all the source files you need into a `pkg` directory, which is
+referenceable from your own source files.
+
+## Getting started
+
+### Credentials
+
+Because you'll be hitting an API, you will need to retrieve your OpenStack
+credentials and either store them as environment variables or in your local Go
+files. The first method is recommended because it decouples credential
+information from source code, allowing you to push the latter to your version
+control system without any security risk.
+
+You will need to retrieve the following:
+
+* username
+* password
+* tenant name or tenant ID
+* a valid Keystone identity URL
+
+For users that have the OpenStack dashboard installed, there's a shortcut. If
+you visit the `project/access_and_security` path in Horizon and click on the
+"Download OpenStack RC File" button at the top right hand corner, you will
+download a bash file that exports all of your access details to environment
+variables. To execute the file, run `source admin-openrc.sh` and you will be
+prompted for your password.
+
+### Authentication
+
+Once you have access to your credentials, you can begin plugging them into
+gophercloud. The next step is authentication, and this is handled by a base
+"Provider" struct. To get one, you can either pass in your credentials
+explicitly, or tell gophercloud to use environment variables:
+
+```go
+import (
+ "github.com/rackspace/gophercloud"
+ "github.com/rackspace/gophercloud/openstack"
+ "github.com/rackspace/gophercloud/openstack/utils"
+)
+
+// Option 1: Pass in the values yourself
+opts := gophercloud.AuthOptions{
+ IdentityEndpoint: "https://my-openstack.com:5000/v2.0",
+ Username: "{username}",
+ Password: "{password}",
+ TenantID: "{tenant_id}",
+}
+
+// Option 2: Use a utility function to retrieve all your environment variables
+opts, err := utils.AuthOptions()
+```
+
+Once you have the `opts` variable, you can pass it in and get back a
+`ProviderClient` struct:
+
+```go
+provider, err := openstack.AuthenticatedClient(opts)
+```
+
+The `ProviderClient` is the top-level client that all of your OpenStack services
+derive from. The provider contains all of the authentication details that allow
+your Go code to access the API - such as the base URL and token ID.
+
+### Provision a server
+
+Once we have a base Provider, we inject it as a dependency into each OpenStack
+service. In order to work with the Compute API, we need a Compute service
+client; which can be created like so:
+
+```go
+client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{
+ Region: os.Getenv("OS_REGION_NAME"),
+})
+```
+
+We then use this `client` for any Compute API operation we want. In our case,
+we want to provision a new server - so we invoke the `Create` method and pass
+in the flavor ID (hardware specification) and image ID (operating system) we're
+interested in:
+
+```go
+import "github.com/rackspace/gophercloud/openstack/compute/v2/servers"
+
+server, err := servers.Create(client, servers.CreateOpts{
+ Name: "My new server!",
+ FlavorRef: "flavor_id",
+ ImageRef: "image_id",
+}).Extract()
+```
+
+If you are unsure about what images and flavors are, you can read our [Compute
+Getting Started guide](http://gophercloud.io/docs/compute). 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/rackspace/gophercloud) struct).
+
+### Next steps
+
+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)
+
+## 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
+[e-mail us](mailto:sdk-support@rackspace.com) privately. You don't need to be a
+Go expert - all members of the community are welcome!
+
+## 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 e-mail us directly at
+[sdk-support@rackspace.com](mailto:sdk-support@rackspace.com).