Merge pull request #692 from jonboulle/master

Clean up README and merge new contribution guidelines

CONTRIBUTING.md

@@ -1,17 +1,13 @@
 # How to contribute
 
-etcd is open source, Apache 2.0 licensed and accepts contributions via Github pull requests.
-This document outlines some of the conventions on commit message formatting, contact points for developers and other resources to make getting your contribution into etcd easier.
+etcd is Apache 2.0 licensed and accepts contributions via Github pull requests. This document outlines some of the conventions on commit message formatting, contact points for developers and other resources to make getting your contribution into etcd easier.
 
 # Email and chat
 
-For simplicity etcd discussions happen on coreos-dev and in #coreos-dev.
-As the community grows we will move to a dedicated mailing list and IRC channel.
-
-- Email: [coreos-dev](https://groups.google.com/forum/#!forum/coreos-dev) 
+- Email: [etcd-dev](http://coreos.com/lists/etcd-dev/)
 - IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) IRC channel on freenode.org
 
-## Getting Started
+## Getting started
 
 - Fork the repository on GitHub
 - Read the README.md for build instructions
@@ -22,11 +18,11 @@ This is a rough outline of what a contributor's workflow looks like:
 
 - Create a topic branch from where you want to base your work. This is usually master.
 - Make commits of logical units.
-- Make sure your commit messages are in the proper format, see below
+- Make sure your commit messages are in the proper format (see below).
 - Push your changes to a topic branch in your fork of the repository.
-- Submit a pull request to coreos/etcd
+- Submit a pull request to coreos/etcd.
 
-Thanks for you contributions!
+Thanks for your contributions!
 
 ### Code style
 
@@ -36,8 +32,7 @@ Please follow this style to make etcd easy to review, maintain and develop.
 
 ### Format of the commit message
 
-etcd follow a rough convention for commit messages borrowed from Angularjs.
-This is an example of a commit:
+etcd follows a rough convention for commit messages borrowed from Angularjs. This is an example of a commit:
 
 ```
     feat(scripts/test-cluster): add a cluster test command
@@ -46,7 +41,7 @@ This is an example of a commit:
     start for debugging.
 ```
 
-To make it more formal it looks something like this:
+The format can be more formally described as follows:
 
 ```
 <type>(<scope>): <subject>
@@ -56,14 +51,14 @@ To make it more formal it looks something like this:
 <footer>
 ```
 
-The first line is the subject and should not be longer than 70 characters, the second line is always blank and other lines should be wrapped at 80 characters.
-This allows the message to be easier to read on github as well as in various git tools.
+The first line is the subject and should be no longer than 70 characters, the second line is always blank, and other lines should be wrapped at 80 characters.  This allows the message to be easier to read on github as well as
+in various git tools.
 
 ### Subject line
 
-The subject line contains succinct description of the change.
+The subject line contains a succinct description of the change.
 
-### Allowed <type>
+### Allowed <type>s
 - feat (feature)
 - fix (bug fix)
 - docs (documentation)
@@ -72,9 +67,9 @@ The subject line contains succinct description of the change.
 - test (when adding missing tests)
 - chore (maintain)
 
-### Allowed <scope>
+### Allowed <scope>s
 
-Scopes could be anything specifying place of the commit change. For example store, api, etc.
+Scopes can be anything specifying the place of the commit change within the repository. For example, "store", "API", etc.
 
 ### More details on commits
 

DCO

@@ -0,0 +1,36 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+660 York Street, Suite 102,
+San Francisco, CA 94110 USA
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

README.md

@@ -3,18 +3,20 @@
 README version 0.3.0
 
 A highly-available key value store for shared configuration and service discovery.
-etcd is inspired by zookeeper and doozer, with a focus on:
+etcd is inspired by [Apache ZooKeeper][zookeeper] and [doozer][doozer], with a focus on being:
 
-* Simple: curl'able user facing API (HTTP+JSON)
-* Secure: optional SSL client cert authentication
-* Fast: benchmarked 1000s of writes/s per instance
-* Reliable: Properly distributed using Raft
+* *Simple*: curl'able user facing API (HTTP+JSON)
+* *Secure*: optional SSL client cert authentication
+* *Fast*: benchmarked 1000s of writes/s per instance
+* *Reliable*: properly distributed using Raft
 
-Etcd is written in Go and uses the [Raft][raft] consensus algorithm to manage a highly-available replicated log.
+etcd is written in Go and uses the [Raft][raft] consensus algorithm to manage a highly-available replicated log.
 
 See [etcdctl][etcdctl] for a simple command line client.
 Or feel free to just use curl, as in the examples below.
 
+[zookeeper]: http://zookeeper.apache.org/
+[doozer]: https://github.com/ha/doozerd
 [raft]: http://raftconsensus.github.io/
 [etcdctl]: http://github.com/coreos/etcdctl/
 
@@ -22,7 +24,7 @@ Or feel free to just use curl, as in the examples below.
 
 ### Getting etcd
 
-The latest release and setup instructions are available at [Github][github-release].
+The latest release and setup instructions are available at [GitHub][github-release].
 
 [github-release]: https://github.com/coreos/etcd/releases/
 
@@ -45,13 +47,13 @@ _NOTE_: you need go 1.2+. Please check your installation with
 go version
 ```
 
-See the [development tools documentation][development-tools.md] for alternative build methods like using Vagrant.
+See the [development tools documentation][development-tools] for alternative build methods like using Vagrant.
 
-[development-tools.md]: https://github.com/coreos/etcd/blob/master/Documentation/development-tools.md
+[development-tools]: https://github.com/coreos/etcd/blob/master/Documentation/development-tools.md
 
 ### Running
 
-First start a single machine cluster of etcd:
+First start a single-machine cluster of etcd:
 
 ```sh
 ./bin/etcd
@@ -59,43 +61,43 @@ First start a single machine cluster of etcd:
 
 This will bring up etcd listening on port 4001 for client communication and on port 7001 for server-to-server communication.
 
-Next lets set a single key and then retrieve it:
+Next, let's set a single key, and then retrieve it:
 
 ```
 curl -L http://127.0.0.1:4001/v2/keys/mykey -XPUT -d value="this is awesome"
 curl -L http://127.0.0.1:4001/v2/keys/mykey
 ```
 
-You have successfully started an etcd on a single machine and written a key to the store. Now it time to dig into the full etcd API and other guides.
+You have successfully started an etcd on a single machine and written a key to the store. Now it's time to dig into the full etcd API and other guides.
 
 ### Next Steps
 
-- Explore the full [API][api.md].
-- Setup a [multi-machine cluster][clustering.md].
-- Learn the [config format, env variables and flags][configuration.md].
-- Find [language bindings and tools][libraries-and-tools.md].
-- Learn about the dashboard, lock and leader election [modules][modules.md].
-- Use TLS to [secure an etcd cluster][security.md].
-- [Tune etcd][tuning.md].
-
-[api.md]: https://github.com/coreos/etcd/blob/master/Documentation/api.md
-[clustering.md]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md
-[configuration.md]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md
-[libraries-and-tools.md]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md
-[modules.md]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md
-[security.md]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
-[tuning.md]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md
+- Explore the full [API][api].
+- Set up a [multi-machine cluster][clustering].
+- Learn the [config format, env variables and flags][configuration].
+- Find [language bindings and tools][libraries-and-tools].
+- Learn about the dashboard, lock and leader election [modules][modules].
+- Use TLS to [secure an etcd cluster][security].
+- [Tune etcd][tuning].
+
+[api]: https://github.com/coreos/etcd/blob/master/Documentation/api.md
+[clustering]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md
+[configuration]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md
+[libraries-and-tools]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md
+[modules]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md
+[security]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
+[tuning]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md
 
 ## Contact
 
-- Mailing list: http://coreos.com/lists/etcd-dev/
-- IRC: #coreos on irc.freenode.net
-- Planning/Roadmap: https://trello.com/b/OiEbU547/etcd
-- Bugs: https://github.com/coreos/etcd/issues
+- Mailing list: [etcd-dev](http://coreos.com/lists/etcd-dev/)
+- IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) oon freenode.org
+- Planning/Roadmap: [milestones](https://github.com/coreos/etcd/issues/milestones)
+- Bugs: [issues](https://github.com/coreos/etcd/issues)
 
 ## Contributing
 
-See [CONTRIBUTING](https://github.com/coreos/etcd/blob/master/CONTRIBUTING.md) for details on submitting patches and contacting developers via IRC and mailing lists.
+See [CONTRIBUTING](CONTRIBUTING.md) for details on submitting patches and the contribution workflow.
 
 ## Project Details
 
@@ -103,7 +105,7 @@ See [CONTRIBUTING](https://github.com/coreos/etcd/blob/master/CONTRIBUTING.md) f
 
 #### Service Versioning
 
-etcd uses [semantic versioning][semver].
+etcd uses [semantic versioning](http://semver.org)
 New minor versions may add additional features to the API.
 
 You can get the version of etcd by issuing a request to /version:
@@ -112,8 +114,6 @@ You can get the version of etcd by issuing a request to /version:
 curl -L http://127.0.0.1:4001/version
 ```
 
-[semver]: http://semver.org/
-
 #### API Versioning
 
 Clients are encouraged to use the `v2` API. The `v1` API will not change.
@@ -124,6 +124,4 @@ During the pre-v1.0.0 series of releases we may break the API as we fix bugs and
 
 ### License
 
-etcd is under the Apache 2.0 license. See the [LICENSE][license] file for details.
-
-[license]: https://github.com/coreos/etcd/blob/master/LICENSE
+etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.