vitalif
/
etcd
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

docs(readme/contrib): clean up README, merge changes from CONTRIBUTING.md and split out DCO

release-0.4
Jonathan Boulle 2014-04-04 10:58:34 -07:00
parent d8a53ca716
commit fd9ad4fa2c
3 changed files with 85 additions and 56 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

33
CONTRIBUTING.md
View File

@ -1,17 +1,13 @@
# How to contribute # How to contribute
etcd is open source, Apache 2.0 licensed and accepts contributions via Github pull requests. 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.
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 # Email and chat
For simplicity etcd discussions happen on coreos-dev and in #coreos-dev. - Email: [etcd-dev](http://coreos.com/lists/etcd-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)
- IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) IRC channel on freenode.org - IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) IRC channel on freenode.org
## Getting Started ## Getting started
- Fork the repository on GitHub - Fork the repository on GitHub
- Read the README.md for build instructions - 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. - Create a topic branch from where you want to base your work. This is usually master.
- Make commits of logical units. - 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. - 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 ### Code style
@ -36,8 +32,7 @@ Please follow this style to make etcd easy to review, maintain and develop.
### Format of the commit message ### Format of the commit message
etcd follow a rough convention for commit messages borrowed from Angularjs. etcd follows a rough convention for commit messages borrowed from Angularjs. This is an example of a commit:
This is an example of a commit:
``` ```
feat(scripts/test-cluster): add a cluster test command feat(scripts/test-cluster): add a cluster test command
@ -46,7 +41,7 @@ This is an example of a commit:
start for debugging. 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> <type>(<scope>): <subject>
@ -56,14 +51,14 @@ To make it more formal it looks something like this:
<footer> <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. 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
This allows the message to be easier to read on github as well as in various git tools. in various git tools.
### Subject line ### 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) - feat (feature)
- fix (bug fix) - fix (bug fix)
- docs (documentation) - docs (documentation)
@ -72,9 +67,9 @@ The subject line contains succinct description of the change.
- test (when adding missing tests) - test (when adding missing tests)
- chore (maintain) - 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 ### More details on commits

36
DCO Normal file
View File

@ -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.

72
README.md
View File

@ -3,18 +3,20 @@
README version 0.3.0 README version 0.3.0
A highly-available key value store for shared configuration and service discovery. 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) * *Simple*: curl'able user facing API (HTTP+JSON)
* Secure: optional SSL client cert authentication * *Secure*: optional SSL client cert authentication
* Fast: benchmarked 1000s of writes/s per instance * *Fast*: benchmarked 1000s of writes/s per instance
* Reliable: Properly distributed using Raft * *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. See [etcdctl][etcdctl] for a simple command line client.
Or feel free to just use curl, as in the examples below. 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/ [raft]: http://raftconsensus.github.io/
[etcdctl]: http://github.com/coreos/etcdctl/ [etcdctl]: http://github.com/coreos/etcdctl/
@ -22,7 +24,7 @@ Or feel free to just use curl, as in the examples below.
### Getting etcd ### 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/ [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 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 ### Running
First start a single machine cluster of etcd: First start a single-machine cluster of etcd:
```sh ```sh
./bin/etcd ./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. 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 -XPUT -d value="this is awesome"
curl -L http://127.0.0.1:4001/v2/keys/mykey 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 ### Next Steps
- Explore the full [API][api.md]. - Explore the full [API][api].
- Setup a [multi-machine cluster][clustering.md]. - Set up a [multi-machine cluster][clustering].
- Learn the [config format, env variables and flags][configuration.md]. - Learn the [config format, env variables and flags][configuration].
- Find [language bindings and tools][libraries-and-tools.md]. - Find [language bindings and tools][libraries-and-tools].
- Learn about the dashboard, lock and leader election [modules][modules.md]. - Learn about the dashboard, lock and leader election [modules][modules].
- Use TLS to [secure an etcd cluster][security.md]. - Use TLS to [secure an etcd cluster][security].
- [Tune etcd][tuning.md]. - [Tune etcd][tuning].
[api.md]: https://github.com/coreos/etcd/blob/master/Documentation/api.md [api]: https://github.com/coreos/etcd/blob/master/Documentation/api.md
[clustering.md]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md [clustering]: https://github.com/coreos/etcd/blob/master/Documentation/clustering.md
[configuration.md]: https://github.com/coreos/etcd/blob/master/Documentation/configuration.md [configuration]: 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 [libraries-and-tools]: https://github.com/coreos/etcd/blob/master/Documentation/libraries-and-tools.md
[modules.md]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md [modules]: https://github.com/coreos/etcd/blob/master/Documentation/modules.md
[security.md]: https://github.com/coreos/etcd/blob/master/Documentation/security.md [security]: https://github.com/coreos/etcd/blob/master/Documentation/security.md
[tuning.md]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md [tuning]: https://github.com/coreos/etcd/blob/master/Documentation/tuning.md
## Contact ## Contact
- Mailing list: http://coreos.com/lists/etcd-dev/ - Mailing list: [etcd-dev](http://coreos.com/lists/etcd-dev/)
- IRC: #coreos on irc.freenode.net - IRC: #[coreos](irc://irc.freenode.org:6667/#coreos) oon freenode.org
- Planning/Roadmap: https://trello.com/b/OiEbU547/etcd - Planning/Roadmap: [milestones](https://github.com/coreos/etcd/issues/milestones)
- Bugs: https://github.com/coreos/etcd/issues - Bugs: [issues](https://github.com/coreos/etcd/issues)
## Contributing ## 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 ## Project Details
@ -103,7 +105,7 @@ See [CONTRIBUTING](https://github.com/coreos/etcd/blob/master/CONTRIBUTING.md) f
#### Service Versioning #### Service Versioning
etcd uses [semantic versioning][semver]. etcd uses [semantic versioning](http://semver.org)
New minor versions may add additional features to the API. New minor versions may add additional features to the API.
You can get the version of etcd by issuing a request to /version: 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 curl -L http://127.0.0.1:4001/version
``` ```
[semver]: http://semver.org/
#### API Versioning #### API Versioning
Clients are encouraged to use the `v2` API. The `v1` API will not change. 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 ### License
etcd is under the Apache 2.0 license. See the [LICENSE][license] file for details. etcd is under the Apache 2.0 license. See the [LICENSE](LICENSE) file for details.
[license]: https://github.com/coreos/etcd/blob/master/LICENSE