docs(readme/contrib): clean up README, merge changes from CONTRIBUTING.md and split out DCO
parent
d8a53ca716
commit
fd9ad4fa2c
|
@ -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
|
||||||
|
|
||||||
|
|
|
@ -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
72
README.md
|
@ -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
|
|
||||||
|
|
Loading…
Reference in New Issue