From 502bbe8742580b7e0b6eaeefbd89ef65a49d5c5a Mon Sep 17 00:00:00 2001
From: Chenxiong Qi <cqi@redhat.com>
Date: Nov 06 2017 09:19:29 +0000
Subject: Reformat README and add more content


* Wrap lines in order to make it more readable in text editor as well.
* Fix indentation in section "List of Freshmaker handlers".
* Add new section Messaging to list existing event and messaging
  information.

Signed-off-by: Chenxiong Qi <cqi@redhat.com>

---

diff --git a/README.md b/README.md
index a7f72bd..65e201e 100644
--- a/README.md
+++ b/README.md
@@ -2,15 +2,27 @@
 
 ## Design
 
-Freshmaker waits for new fedmsg messages, this happens in `consumer.py`. Every fedmsg message handled by a Freshmaker is parsed by one of the parsers which can be found in the `parsers` directory. This parser converts the fedmsg to trigger object (inherits from `BaseTrigger`). All the triggers are defined in the `triggers.py`. This separation between message and trigger is done to possibly support different messaging backends in the future or easily change the message we react to. This trigger object is then handled by one or more handlers defined in the `handlers` directory.
+Freshmaker waits for new fedmsg messages, this happens in `consumer.py`. Every
+fedmsg message handled by a Freshmaker is parsed by one of the parsers which can
+be found in the `parsers` directory. This parser converts the fedmsg to trigger
+object (inherits from `BaseTrigger`). All the triggers are defined in the
+`triggers.py`. This separation between message and trigger is done to possibly
+support different messaging backends in the future or easily change the message
+we react to. This trigger object is then handled by one or more handlers defined
+in the `handlers` directory.
 
 The example flow for the modulemd yaml change in dist-git is following:
 
-- Message from dist-git is received, ModuleMetadataUpdated trigger is generated out of this message and the trigger event is passed to handlers.
+- Message from dist-git is received, `ModuleMetadataUpdated` trigger is
+  generated out of this message and the trigger event is passed to handlers.
 - MBS handler handles this message and triggers the rebuild of a module in MBS.
-- MBS rebuilds the module and generates message, this message is received and parsed by Freshmaker. ModuleBuilt trigger is generated and passed to handlers.
-- MBS handler handles this message if another modules depend on the built module and triggers the rebuild of these modules.
-- OSBS handler handles this message if some containers depend on this module and instructs OSBS to rebuild them
+- MBS rebuilds the module and generates message, this message is received and
+  parsed by Freshmaker. `ModuleBuilt` trigger is generated and passed to
+  handlers.
+- MBS handler handles this message if another modules depend on the built module
+  and triggers the rebuild of these modules.
+- OSBS handler handles this message if some containers depend on this module and
+  instructs OSBS to rebuild them
 
 Handlers can be turned on/off in config file.
 
@@ -20,15 +32,24 @@ Following is the list of all available HANDLERS:
 
 * `freshmaker.handlers.koji:KojiTaskStateChangeHandler`
 * `freshmaker.handlers.mbs:MBSModuleStateChangeHandler`
-  * Depends on: MBS, PDC
+    * Depends on: MBS, PDC
 * `freshmaker.handlers.git:GitRPMSpecChangeHandler`
-  * Depends on: PDC
+    * Depends on: PDC
 * `freshmaker.handlers.brew:BrewSignRPMHandler`
-  * Depends on: Errata, LightBlue, Pulp, Koji
+    * Depends on: Errata, LightBlue, Pulp, Koji
 * `freshmaker.handlers.git:GitDockerfileChangeHandler`
 * `freshmaker.handlers.git:GitModuleMetadataChangeHandler`
 * `freshmaker.handlers.bodhi:BodhiUpdateCompleteStableHandler`
-  * Depends on: PDC, Koji
+    * Depends on: PDC, Koji
+
+## Messaging
+
+Freshmaker sends messages to either fedmsg or UMB, which depends on how it is
+configured, when certain event happens.
+
+| Event | Topic |
+|-------|-------|
+| Containers are found and will be built soon | `images.found` |
 
 ## Testing