fix awesomized#82, awesomized#64 and awesomized#21: docs on replication

BUGS.md

@@ -0,0 +1,38 @@
+# Bugs, Known Issues and Insufficiencies
+
+## libhashkit
+
+### MurMur
+
+Hashkit's MurMur/MurMur3 are limited to the lower 32 bits.
+
+### crc32
+
+Commit "[More Hashing methods](./commits/1207354f)" from October 2007
+first released in v0.8, which main intention seems to have been to add 
+FNV1 hash algos, changed the result of the crc32 hash to only its upper 
+16 bits sans MSB, without any additional comment.
+
+The implementations referred to in the file header (Postgres and BSD)
+do not exhibit this behavior.
+
+A [bug report](https://bugs.launchpad.net/libmemcached/+bug/604178) was
+filed three years later on launchpad, which was marked `Won't fix` with
+the comment that it was for compatibility with other "drivers", which
+supposedly refers to other memcached client libraries.
+
+
+## libmemcached
+
+### Replication
+
+This is a somewhat badly named feature, because it **does not** provide
+any of the guaranties one would expect from a proper replication.
+
+One can set the intended number of additional servers where data should
+be stored with the behavior `MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS` and
+specify whether `MGET`s/`GET`s should read from a random server with 
+`MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ`. `DELETE`s will try to 
+delete the key from all replicas.
+
+The binary protocol is required and any other command is unaffected.

ChangeLog.md

@@ -95,6 +95,10 @@ has been incremented due to the following changes:
 * Fix bin/memaslap to idnentify itself as memaslap instead of memslap.
 * Fix bin/memcapable to work with memcached >= 1.6.
 * Fix murmur and murmur3 hashes on big endian platforms.
+* Fix [gh #82](https://github.com/m6w6/libmemcached/issues/82),
+  [gh #64](https://github.com/m6w6/libmemcached/issues/64) and
+  [gh #21](https://github.com/m6w6/libmemcached/issues/21):
+  clarify documentation on replication.
 
 ---
 

README.md

@@ -67,6 +67,10 @@ found in the accompanying [LICENSE](./LICENSE) file.
 
 ## Contributing
 
+Please report any issues on the [bug tracker](https://github.com/m6w6/libmemcached/issues).
+
+A list of known permanent issues is maintained in [BUGS](./BUGS.md).
+
 All forms of contribution are welcome! Please see the bundled
 [CONTRIBUTING](./CONTRIBUTING.md) note for the general principles followed.
 

docs/source/libmemcached/memcached_behavior.rst

@@ -222,23 +222,29 @@ SYNOPSIS
 
     .. enumerator:: MEMCACHED_BEHAVIOR_NUMBER_OF_REPLICAS
 
-        Specify the numbers of replicas `libmemcached` should store of each item
+        Specify the number of replicas `libmemcached` should store of each item
         (on different servers).
 
         This replication does not dedicate certain memcached servers to store
         the replicas in, but instead it will store the replicas together with
         all of the other objects (on the 'n' next servers specified in your
         server list).
 
+        Requires the binary protocol and only supports (M)GET/SET/DELETE.
+
+        **NOTE**: `libmemcached` does not guarantee nor enforce any consistency.
+
     .. enumerator:: MEMCACHED_BEHAVIOR_RANDOMIZE_REPLICA_READ
 
         Allows randomizing the replica reads starting point. Normally the read
-        is done from primary server and in case of miss the read is done from
+        is done from primary server and in case of failure the read is done from
         primary + 1, then primary + 2 all the way to 'n' replicas.
 
-        If this option is set on the starting point of the replica reads is
-        randomized between the servers.  This allows distributing read load to
-        multiple servers with the expense of more write traffic.
+        This allows distributing read load to multiple servers with the expense
+        of more write traffic.
+
+        **NOTE**: Only errors to communicate with a server are considered 
+        failures, so `MEMCACHED_NOTFOUND` does *not* account for failure.
 
     .. enumerator:: MEMCACHED_BEHAVIOR_CORK