From 8a8912ace9e4ef0bb9f48c63148f40a6e28b390d Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Fri, 9 Aug 2013 17:15:44 -0700 Subject: [PATCH 1/3] chore(README): add the travis badge lower the travis badge was located above the title which looked a bit weird, move it down. --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index f948a5e9cd..f31cd2a2ac 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ -[![Build Status](https://travis-ci.org/benbjohnson/go-raft.png?branch=master)](https://travis-ci.org/benbjohnson/go-raft) - go-raft ======= +[![Build Status](https://travis-ci.org/benbjohnson/go-raft.png?branch=master)](https://travis-ci.org/benbjohnson/go-raft) + ## Overview This is an Go implementation of the Raft distributed consensus protocol. From c8de7dbb6e40bce470e6c2a61bde979cd5d3e25d Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Fri, 9 Aug 2013 17:29:43 -0700 Subject: [PATCH 2/3] chore(README): add an introduction section to the Overview Add an introduction to the overview and put a link at the bottom. --- README.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index f31cd2a2ac..392541b5f9 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,9 @@ For more details on Raft, you can read [In Search of an Understandable Consensus ## The Raft Protocol +This section provides a short simple summary of the Raft protocol from a high level. +For a more detailed explanation on the failover process and election terms please see the full paper describing the protocol: [In Search of an Understandable Consensus Algorithm][raft-paper]. + ### Overview Maintaining state in a single process on a single server is easy. @@ -26,7 +29,7 @@ Servers can crash or the network between two machines can become unavailable or A distributed consensus protocol is used for maintaining a consistent state across multiple servers in a cluster. Many distributed systems are built upon the Paxos protocol but Paxos can be difficult to understand and there are many gaps between Paxos and real world implementation. -An alternative is the [Raft distributed consensus protocol](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf) by Diego Ongaro and John Ousterhout. +An alternative is the [Raft distributed consensus protocol][raft-paper] by Diego Ongaro and John Ousterhout. Raft is a protocol built with understandability as a primary tenant and it centers around two things: 1. Leader Election @@ -53,9 +56,6 @@ By ensuring that this log is replicated identically between all the nodes in the Replicating the log under normal conditions is done by sending an `AppendEntries` RPC from the leader to each of the other servers in the cluster (called Peers). Each peer will append the entries from the leader through a 2-phase commit process which ensure that a majority of servers in the cluster have entries written to log. -For a more detailed explanation on the failover process and election terms please see the full paper describing the protocol: [In Search of an Understandable Consensus Algorithm](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf) - - ## Project Status The go-raft library is feature complete but in alpha. @@ -67,3 +67,4 @@ However, I hope other projects can benefit from having a distributed consensus p If you have a project that you're using go-raft in, please add it to this README and send a pull request so others can see implementation examples. If you have any questions on implementing go-raft in your project, feel free to contact me on [GitHub](https://github.com/benbjohnson), [Twitter](https://twitter.com/benbjohnson) or by e-mail at [ben@skylandlabs.com](mailto:ben@skylandlabs.com). +[raft-paper]: https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf From dbed707bdb0c8cc2112ef9efb3b33d7dea367f86 Mon Sep 17 00:00:00 2001 From: Brandon Philips Date: Fri, 9 Aug 2013 18:03:03 -0700 Subject: [PATCH 3/3] feat(README): reorganize assuming someone knows raft People who find this repo probably already know a bit about raft. So, lets tell them about the current state of the project, the features that are implemented and the example projects first. --- README.md | 41 +++++++++++++++++++++++++++++++---------- 1 file changed, 31 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 392541b5f9..3795fc211a 100644 --- a/README.md +++ b/README.md @@ -9,8 +9,35 @@ This is an Go implementation of the Raft distributed consensus protocol. Raft is a protocol by which a cluster of nodes can maintain a replicated state machine. The state machine is kept in sync through the use of a replicated log. -For more details on Raft, you can read [In Search of an Understandable Consensus Algorithm](https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf) by Diego Ongaro and John Ousterhout. +For more details on Raft, you can read [In Search of an Understandable Consensus Algorithm][raft-paper] by Diego Ongaro and John Ousterhout. +## Project Status + +This library is feature complete but should be considered experimental until it has seen more usage. +If you have any questions on implementing go-raft in your project please file an issue. +There is an [active community][community] of developers who can help. +go-raft is under the MIT license. + +[community]: https://github.com/benbjohnson/go-raft/contributors + +### Features + +- Leader election +- Log replication +- Configuration changes +- Log compaction +- Unit tests +- Fast Protobuf Log Encoding +- HTTP transport + +### Projects + +These projects are use go-raft: + +- [coreos/etcd](https://github.com/coreos/etcd) - A highly-available key value store for shared configuration and service discovery +- [benbjohnson/raftd](https://github.com/benbjohnson/raftd) - A reference implementation for using the go-raft library for distributed consensus. + +If you have a project that you're using go-raft in, please add it to this README so others can see implementation examples. ## The Raft Protocol @@ -56,15 +83,9 @@ By ensuring that this log is replicated identically between all the nodes in the Replicating the log under normal conditions is done by sending an `AppendEntries` RPC from the leader to each of the other servers in the cluster (called Peers). Each peer will append the entries from the leader through a 2-phase commit process which ensure that a majority of servers in the cluster have entries written to log. -## Project Status +## History -The go-raft library is feature complete but in alpha. -There is a reference implementation called [raftd](https://github.com/benbjohnson/raftd) that demonstrates how to use the library +Ben Johnson started this library for use in his behavioral analytics database called [Sky](https://github.com/skydb/sky). +He put it under the MIT license in the hopes that it would be useful for other projects too. -The library will be considered experimental until it has significant production usage. -I'm writing the library for the purpose of including distributed processing in my behavioral analytics database called [Sky](https://github.com/skydb/sky). -However, I hope other projects can benefit from having a distributed consensus protocol so the go-raft library is available under MIT license. - -If you have a project that you're using go-raft in, please add it to this README and send a pull request so others can see implementation examples. -If you have any questions on implementing go-raft in your project, feel free to contact me on [GitHub](https://github.com/benbjohnson), [Twitter](https://twitter.com/benbjohnson) or by e-mail at [ben@skylandlabs.com](mailto:ben@skylandlabs.com). [raft-paper]: https://ramcloud.stanford.edu/wiki/download/attachments/11370504/raft.pdf