add docs for 0.3.0

MANIFEST.in

@@ -1,5 +1,5 @@
 include versioneer.py
 include src/wormhole/_version.py
-include LICENSE README.md
+include LICENSE README.md NEWS.md
 recursive-include docs *.md *.rst
 

NEWS.md

@@ -0,0 +1,19 @@
+
+User-visible changes in "magic-wormhole":
+
+## Release 0.3.0 (24-Jun-2015)
+
+Add preliminary Twisted support, only for symmetric endpoints (no
+initator/receiver distinction). Lacks code-entry tab-completion. May still
+leave timers lingering. Add test suite (only for Twisted, so far).
+
+Use a sqlite database for Relay server state, to survive reboots with less
+data loss. Add "--advertise-version=" to "wormhole relay start", to override
+the version we recommend to clients.
+
+## Release 0.2.0 (10-Apr-2015)
+
+Initial release: supports blocking/synchronous asymmetric endpoints
+(Initiator on one side, Receiver on the other). Codes can be generated by
+Initiator, or created externally and passed into both (as long as they start
+with digits: NNN-anything).

README.md

@@ -113,12 +113,13 @@ All four commands accept:
 ## Library
 
 The `wormhole` module makes it possible for other applications to use these
-code-protected channels. The current release only includes
-blocking/synchronous support, but a future release will include async/Twisted
-libraries too. The main module is named `wormhole.blocking.transcribe`, to
-reflect that it is for synchronous/blocking code, and uses a PAKE mode
-whereby one user transcribes their code to the other. (internal names may
-change in the future). There are distinctive sides: one `Initiator`, and one
+code-protected channels. This includes blocking/synchronous support (for an
+asymmetric pair of "initiator" and "receiver" endpoints), and async/Twisted
+support (for a symmetric scheme). The main module is named
+`wormhole.blocking.transcribe`, to reflect that it is for
+synchronous/blocking code, and uses a PAKE mode whereby one user transcribes
+their code to the other. (internal names may change in the future). The
+synchronous support uses distinctive sides: one `Initiator`, and one
 `Receiver`.
 
 The file-transfer tools use a second module named
@@ -138,7 +139,7 @@ This library is intended to be compatible with python2.6, 2.7, 3.3, and 3.4,
 although proper tests have not yet been implemented.
 
 It depends upon the SPAKE2, pynacl, requests, and argparse libraries. To run
-a relay server, you must also install Twisted.
+a relay server or use the async support, you must also install Twisted.
 
 
 #### footnotes

docs/api.md

@@ -88,6 +88,27 @@ both sides are the same, call `d=get_data()` to continue the transfer. If you
 call `get_data()` first, it will perform the complete transfer without
 pausing.
 
+## Generating the Invitation Code
+
+In most situations, the Initiator will call `i.get_code()` to generate the
+invitation code. This returns a string in the form `NNN-code-words`. The
+numeric "NNN" prefix is the "channel id", and is a short integer allocated by
+talking to the rendezvous server. The rest is a randomly-generated selection
+from the PGP wordlist, providing a default of 16 bits of entropy. The
+initiating program should display this code to the user, who should
+transcribe it to the receiving user, who gives it to the Receiver object by
+calling `r.set_code()`. The receiving program can also use
+`input_code_with_completion()` to use a readline-based input function: this
+offers tab completion of allocated channel-ids and known codewords.
+
+Alternatively, the human users can agree upon an invitation code themselves,
+and provide it to both programs later (with `i.set_code()` and
+`r.set_code()`). They should choose a channel-id that is unlikely to already
+be in use (3 or more digits are recommended), append a hyphen, and then
+include randomly-selected words or characters. Dice, coin flips, shuffled
+cards, or repeated sampling of a high-resolution stopwatch are all useful
+techniques.
+
 
 ## Application Identifier
 
@@ -114,7 +135,9 @@ This library includes the URL of a public relay run by the author.
 Application developers can use this one, or they can run their own (see
 src/wormhole/servers/relay.py) and configure their clients to use it instead.
 
-## Polling and Shutdown (TODO)
+## Polling and Shutdown
+
+TODO: this is mostly imaginary
 
 The reactor-based (Twisted-style) forms of these objects need to establish
 TCP connections, re-establish them if they are lost, and sometimes (for