1 files changed, 30 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..3537697
--- /dev/null
+++ b/README.md
@@ -0,0 +1,30 @@
+# Implementation of RFC 1982 Serial Number Arithmetic.
+
+Run as a program, this takes start and finish serial values and tells
+you what intermediate steps (if any) are needed to make the specified
+change.
+
+Used as a module, this implements the `Serial` class and an iterator
+which returns the intermediate steps (if any) needed between two
+`Serial` values.
+
+Per the RFC, only two operations are defined on `Serial` objects:
+addition and comparision, both within a restricted range specified
+by the RFC.
+
+The default modulus is `2**32`, you can change this by subclassing the
+`Serial` and overriding the class's `modulus` variable.  The modulus
+must be a power of two.
+
+See RFC 1982 for discussion of the ways in which serial numbers do not
+work like normal integers.  In particular, note that there's a corner
+case in which one can have a pair of serial numbers `I1` and `I2`
+where `I1` is neither equal to, less than, nor greater than `I2`.
+This is deliberate and is not a bug in the code.  See the RFC.
+
+The `find_intermediate()` iterator takes two `Serial` values `start`
+and `finish` and yields the sequence of intermediate values (if any)
+needed to step from `start` to `finish`.
+
+There are also a couple of test programs that use `random.randint()`
+to generate test values.  Maybe someday I'll recode with `unittest`.