Merge 8487e71 into 0ccad47

.travis.yml

@@ -38,7 +38,7 @@ deploy:
   script: 'bundle exec s3_website push --verbose'
   skip_cleanup: true
   on:
-    tags: true
+    branch: 'master'
     repo: 'marvinpinto/charlesbot'
 
 after_deploy:

docs/architecture.rst

@@ -0,0 +1,33 @@
+Architecture
+============
+
+At its core, Charlesbot essentially works as follows:
+
+.. image:: _static/images/charlesbot_architecture.png
+   :alt: Charlesbot Architecture
+
+When a message comes in through a Slack websocket, ``robot.py`` delivers a copy
+of the message to each Charlesbot plugin. This is done by pushing this message
+onto each plugin's queue, at which point the plugin is free to consume the
+message on its own schedule.
+
+This approach decouples the processing of a message from the receiving of a
+message, which helps in a scenario where a channel is flooded with more
+incoming messages than a plugin is able to handle (in a timely manner).
+
+Abstract Base Class
+-------------------
+
+The abstract base class ``BasePlugin`` handles the bulk of the message
+coordination which allows you to write your plugins with minimum boiler plate.
+
+In order for this to work, you will need to inherit from ``BasePlugin`` and
+implement the plugin logic using at minimum the following two abstract methods:
+
+.. code-block:: python
+
+    def get_help_message(self):
+        pass
+
+    def process_message(self, message):
+        pass

docs/conf.py

@@ -133,6 +133,8 @@
     'analytics_id': os.getenv('GOOGLE_ANALYTICS_ID', "no-google-analytics"),
     'extra_nav_links': {
         "Home Page": 'https://www.charlesbot.org',
+        "GitHub": 'https://github.com/marvinpinto/charlesbot',
+        "Issues": 'https://github.com/marvinpinto/charlesbot/issues',
     }
 }
 

docs/index.rst

@@ -24,3 +24,5 @@ out!
 
     installation
     development
+    roadmap
+    architecture

docs/roadmap.rst

@@ -0,0 +1,51 @@
+Roadmap
+=======
+
+``python-slackclient``
+----------------------
+
+Charlesbot currently uses the python-slackclient__ library to handle the
+underlying websocket communication. I am not *entirely* a fan of this library
+and I intend on replacing it with a native asyncio solution.
+
+__ https://github.com/slackhq/python-slackclient
+
+Plugin Architecture
+-------------------
+
+The plugin architecture for this project has come a long way since the first
+few iterations. It is designed such that plugins can be dropped in place
+without having to modify the core code-base.
+
+This is what the `current architecture`__ looks like.
+
+__ architecture.html
+
+The "queue + worker" system of delivering messages to each plugin is an
+experiment in how much this design will scale, before it starts hogging
+resources and being generally slow. We'll see how it goes!
+
+Configuration Management
+------------------------
+
+One thing that I would like to axe eventually is the way configuration is
+read/written to. I am *not* a fan of supplying config files on the command
+line.
+
+Another alterative to supplying config files on the command line is the
+"everything gets configured through environment variables" (`12 factor-ish`__)
+approach. I feel like this approach is taking it to the other extreme and there
+must be a middle ground somewhere.
+
+I feel like relying on an operator to supply a slew of environment variables on
+the command line can get unwieldy fast! (imagine a chain of 50+ ``-e
+"VAR=foo"`` docker arguments!)
+
+I am hoping to explore an architecture where the basic amount of information
+needed to get going is read from environment variables, and the rest are read
+from a key-value store of sorts. This would allow for things such as
+post-launch configuration and this approach scales nicely if/when Charlesbot is
+restarted as users would not need to go in and reconfigure their
+plugin-specific settings.
+
+__ http://12factor.net