Documentation update on general project status

nzlosh · Oct 26, 2022 · 19cfd9b · 19cfd9b
1 parent a80d38b
commit 19cfd9b
Show file tree

Hide file tree

Showing 3 changed files with 58 additions and 16 deletions.
diff --git a/docs/getting_started.rst b/docs/getting_started.rst
@@ -9,23 +9,22 @@ Getting Started
 Overview
 =========
 
-`err-stackstorm` is a community project to bring StackStorm `ChatOps <https://docs.stackstorm.com/chatops/index.html>`_ to `Errbot <http://errbot.io/en/latest/index.html>`_.  No commercial support is provided by StackStorm.  `err-stackstorm` exposes Stackstorm's `Action Aliases <https://docs.stackstorm.com/chatops/aliases.html>`_ to your chat environment, where you and your team can manage aspects of infrastructure and code.
+`err-stackstorm` is a community project to bring StackStorm `ChatOps <https://docs.stackstorm.com/chatops/index.html>`_ to `Errbot <http://errbot.io/en/latest/index.html>`_ and not officially supported by StackStorm or Errbot maintainers.  `err-stackstorm` enables StackStorm's `Action Aliases <https://docs.stackstorm.com/chatops/aliases.html>`_ in your chat environment, where you and your team can manage aspects of infrastructure, code and 3rd party services.
 
 The objectives for err-stackstorm project are:
- 1. Emulate hubot-stackstorm features.
- 2. Provide a Python friendly ChatOps solution.
- 3. Respect StackStorm's enterprise offering.
- 4. Maintain the same high quality as the StackStorm project.
- 5. Collaborate with the StackStorm community to evolve ChatOps features.
+ 1. Provide a Python friendly ChatOps solution.
+ 1. Maintain the same high quality as the StackStorm project.
+ 3. Collaborate with the StackStorm community to evolve ChatOps features.
+ 4. Match or exceed hubot-stackstorm features.
 
 Features
 ========
 
 err-stackstorm communicates directly with the StackStorm API from with an errbot instance.
 
      - List action-alias help dynamically.  When StackStorm action-aliases are updated, they are immediately available in the err-stackstorm output.  Filtering by pack name and keyword can be used when looking for help.
-     - Access-Control Lists based on any combination of chat username, command and room. ACLs are defined in the errbot configuration file.
-     - Associate StackStorm user credentials with chat usernames.  Client-Side authenticate lets err-stackstorm dynamically map chat user accounts with StackStorm authenicated users.  Credentials are passed via an out of band authentication web page.
+     - Access-Control Lists based on any combination of chat username, command and room.  ACLs are defined in the errbot configuration file.
+     - Associate StackStorm user credentials with chat usernames.  Client-Side authenticate lets err-stackstorm dynamically map chat user accounts with StackStorm authenticated users.  Credentials are passed via an out of band authentication web page.
      - Trigger action-aliases directly from the bot.
      - Support for multiple chat backends, as provided by errbot.
      - Customise plugin prefix.
@@ -40,9 +39,10 @@ The plugin has been developed and tested against the below software combinations
 
 
    .. csv-table:: Ideal Combination of Versions
-      :header: "err-stackstorm", "Python", "Errbot", "Stackstorm Client"
+      :header: "err-stackstorm", "Python", "Errbot", "StackStorm Client"
       :widths: 15, 10, 10, 20
 
+      "2.2", "3.7+", "6.1.9", "not used"
       "2.1", "3.6+", "6.0.0", "not used"
       "2.0", "3.4", "5.2.0", "2.10"
       "1.4", "3.4", "5.1.2", "2.5"
@@ -51,32 +51,46 @@ The plugin has been developed and tested against the below software combinations
       "1.1", "3.4", "4.3", "2.2"
       "1.0", "2.7", "3.x", "2.1"
 
+Platforms
+=========
+
+``err-stackstorm`` is developed and testing on the x86_64 platform for Linux.  No other platforms or operating systems have been tested.
+
+    .. important:: ``err-stackstorm`` has  been reported by users to have issue running on Mac OSX.
 
 Supported Chat Backends
 =========================
 
-Errbot provides official support for most major chat back-ends and many more chat back-ends are available through unofficial plugins.
+Errbot provides official support for most major chat back-ends and many more chat back-ends are available through unofficial community plugins.
 
 
    .. csv-table:: Supported Chat Backends
          :header: "Backend", "Mode value", "Support Type"
          :widths: 10, 10, 10
 
-         "Slack", "slack", "Integrated"
          "Text", "text", "Integrated"
+         "IRC", "irc", "Integrated"
          "XMPP", "xmpp", "Integrated"
-         "Mattermost", "mattermost", "`Plugin <https://github.com/Vaelor/errbot-mattermost-backend>`_"
+         "Slack", "slack", "`Plugin <https://github.com/errbotio/err-backend-slackv3>`_"
+         "Mattermost", "mattermost", "`Plugin <https://github.com/errbotio/err-backend-mattermost>`_"
          "Rocket Chat", "aoikrocketchaterrbot", "`Plugin <https://github.com/AoiKuiyuyou/AoikRocketChatErrbot>`_"
          "Gitter", "gitter", "`Plugin <https://github.com/errbotio/err-backend-gitter>`_"
-         "Discord", "discord", "`Plugin <https://github.com/gbin/err-backend-discord>`_"
+         "Discord", "discord", "`Plugin <https://github.com/errbotio/err-backend-discord>`_"
+
+    .. csv-table:: Unsupported Chat Backends
+        :header: "Backend", "Mode value", "Support Type"
+        :widths: 10, 10, 10
+
+        "MSTeam", "BotFramework", "`Plugin <https://github.com/vasilcovsky/errbot-backend-botframework>`_"
+
+.. important:: ``err-stackstorm`` doesn't support MSTeams due to lack of access by the developer, if you're intersted in adding and maintaining MSTeams support please contact nzlosh on slack/gitter or github.
 
 Backend support provides a minimum set of operations such as `connect` and `authentication` methods along with ways to `identify` and `send messages` to users/rooms.
 
-Advanced formatting may not be available on all backends since additional code would be required in `err-stackstorm` to translate Stackstorm's Action Aliases `extra` parameter.
+Advanced formatting may not be available on all backends since additional code would be required in `err-stackstorm` to translate StackStorm's Action Aliases `extra` parameter.
 
 
 Backends that currently support nice (extra) formatting:
 
    * Slack
    * XMPP
-
diff --git a/docs/linux_package_building.rst b/docs/linux_package_building.rst
@@ -0,0 +1,28 @@
+Building Linux Packages
+=========================================================================================================================================================
+Two scripts are used to help ``err-stackstorm`` packages available on mulitple operating systems.  Each script represent a phase in the package build process
+
+``contrib/packaging/build_archive`` is a BASH script that carries out the steps to create a Python virtual environment and install errbot, various backends and err-stackstorm using a supported operating systems native Python installation.
+
+``contrib/packaging/build`` is a Python script that depends on jinja2.  It should be setup using its own virtual environment and is executed after the err-stackstorm archive has been successfully created by ``build_archive``.  ``build`` reads the ``build.cfg`` configuration file, which is JSON format, to fill out jinja templates that are used by the operating systems package build system.  This allows for updating and build system packages in a similar maner for all supported operating systems.
+
+Phase 1: Packaging Python 
+---------------------------------------------------------------------------------------------------------------------------------------------------------
+Python applications are best isolated from the system.  Python virtual environments (venv) are created for this purpose, the virtual environment is created inside a single directory, various base standard libraries are copied into the venv and symlinks setup to point to the systems Python interpreter.  The venv will be created with whichever version of python was executed to create the venv.
+::
+
+	python3.8 -m venv <venv_name>
+	source <venv_name>/bin/activate
+
+
+Phase 2: Build System packages
+---------------------------------------------------------------------------------------------------------------------------------------------------------
+After the Python virtual environment has been setup, dependencies installed and pre-compiled files purged, the Python virtual environment is archived using ``tar``.  The resulting archive will be used to deploy the virtual environment inside the native OS packaging.
+
+Building DEB based packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TO DO
+
+Building RPM based packages
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+TO DO
diff --git a/docs/quick_start.rst b/docs/quick_start.rst
@@ -51,4 +51,4 @@ If you are familiar with Errbot and StackStorm, this guide will get you up and r
 
 8. Aliases can be run like this: ``!st2 run date on 192.168.5.1``
 
-.. important:: `st2chatops` does not have to be running on your StackStorm instance. This plugin *replaces* `st2chatops`.
+.. important:: When restarting StackStorm, a warning may be produced to inform you `st2chatops` is not running.   This warning can be ignored because `err-stackstorm` will be managing StackStorm ChatOps.
Original file line number	Diff line number	Diff line change
Expand Up		@@ -51,4 +51,4 @@ If you are familiar with Errbot and StackStorm, this guide will get you up and r

		8. Aliases can be run like this: ``!st2 run date on 192.168.5.1``

		.. important:: `st2chatops` does not have to be running on your StackStorm instance. This plugin replaces `st2chatops`.
		.. important:: When restarting StackStorm, a warning may be produced to inform you `st2chatops` is not running. This warning can be ignored because `err-stackstorm` will be managing StackStorm ChatOps.