README.md contents

README.md

@@ -1,4 +1,46 @@
-# RacketMQ
+# RacketMQ: An implementation of W3C WebSub
+
+This is an implementation of a W3C WebSub Hub in Racket, using the
+actor-style research language [Syndicate](http://syndicate-lang.org/).
+
+## What is WebSub?
+
+On the 20th of October 2016, the W3C released a First Public Working
+Draft of (what was called at the time) PubSub, later renamed to
+WebSub.
+
+See the specification of the W3C WebSub protocol at
+<https://www.w3.org/TR/pubsub/> (and track its development at
+<https://github.com/w3c/pubsub>).
+**N.B.: Those URLs will eventually have `websub` in place of `pubsub`.**
+
+## Features
+
+ - Offers both *local topics*, topics whose canonical hub is this hub,
+   and *remote topics*, topics whose canonical hub is some other
+   ("upstream") hub
+
+ - Support for polling and push-notification for remote topics, with
+   configurable poll interval
+
+ - Uses HTTP `Link` headers when retrieving a topic to determine
+   canonical hub and topic URLs; does not extract `link` elements from
+   any kind of XML or HTML document, nor does it implement
+   `.host-meta` discovery
+
+ - Support for `hub.secret` and `hub.lease_seconds` protocol
+   parameters
+
+## Conformance
+
+At the time of writing, no official list of conformance criteria
+exists; however, there is a draft list of Candidate Recommendation
+implementation criteria at <https://github.com/w3c/pubsub/issues/56>.
+
+## Bug Reports
+
+Please report issues using this project's Github issues page,
+<https://github.com/tonyg/racketmq/issues>.
 
 ## License