codeoverflow-org · J0B10 · Jul 21, 2019 · Jul 9, 2019 · Jul 9, 2019 · Jul 9, 2019
diff --git a/.synchronize-wiki.sh b/.synchronize-wiki.sh
@@ -17,4 +17,6 @@ git rm .travis.yml --cached
 git commit --message "Synchronized wiki (Travis build #$TRAVIS_BUILD_NUMBER)"
 
 echo "Pushing wiki..."
-git push --force wiki master
+git push --force wiki master
+
+# This file is not included in the wiki.
diff --git a/.travis.yml b/.travis.yml
@@ -1,8 +1,11 @@
+language: minimal
 notifications:
   email: false
 branches:
   only:
     - master
 script:
   - chmod +x .synchronize-wiki.sh
-  - ./.synchronize-wiki.sh
+  - ./.synchronize-wiki.sh
+
+# This file is not included in the wiki.
diff --git a/Home.md b/Home.md
@@ -1,2 +1,4 @@
+_Wiki for chatoverflow version [0.2-prealpha](https://github.com/codeoverflow-org/chatoverflow/releases/tag/0.2-prealpha)_
+
 Welcome to the Chat Overflow wiki!
 Please see the menu to find more information.
diff --git a/LICENSE b/LICENSE
diff --git a/README.md b/README.md
@@ -1,3 +1,44 @@
 # Chatoverflow wiki
 
-This repository contains the files for the chatoverflow wiki. For more information about the chat overflow project, please visit [chatoverflow.org](http://chatoverflow.org).
+This repository contains the files for the chatoverflow wiki.
+For more information about the chat overflow project, please visit [codeoverflow.org](http://codeoverflow.org).
+
+## Content
+
+**Usage:**  
+1. [Installation](usage/Installation.md)  
+2. [Using the CLI](usage/Using-the-CLI.md)  
+3. [Using the GUI](usage/Using-the-GUI.md)  
+    1. [Starting the Better REPL](usage/Using-the-GUI.md#Starting-the-Better-REPL)  
+    2. [Creating a plugin instance](usage/Using-the-GUI.md#Creating-a-plugin-instance)  
+    3. [Setting plugin requirements](usage/Using-the-GUI.md#Setting-plugin-requirements)  
+    4. [Adding connectors](usage/Using-the-GUI.md#Adding-connectors)  
+    5. [Set credentials](usage/Using-the-GUI.md#Set-credentials)  
+4. [Frequent Issues](usage/Frequent-Issues.md)  
+    1. [Run Configuration Bug](usage/Frequent-Issues.md#Run-Configuration-Bug)  
+    2. [Credentials value encrypted with wrong auth key](usage/Frequent-Issues.md#Credentials-value-encrypted-with-wrong-auth-key)  
+
+**Development:**  
+1. [Writing a plugin](development/Writing-a-plugin.md)  
+2. [Adding a new platform source](development/Adding-a-new-platform-source.md)  
+3. [Deploy ChatOverflow](development/Deploy-ChatOverflow.md)
+4. [Structure](development/Structure.md)
+5. [Pluggable migration guide](development/Pluggable-migration-guide.md)
+
+## Contributing
+
+You have an idea how the wiki could be improved or just found some typos/spelling mistakes?  
+
+Everybody can easily contribute to the wiki:  
+1. Navigate the the right file in this repo
+2. Click on the ✎ icon in the upper right corner
+3. Edit the page 
+4. Enter a message that describes your change and click on `Propose file change`.
+5. We'll review the change and merge it if it fits.
+
+If you are experienced with git you can of course also fork this repo, do commits and create a pull request.
+
+**Thanks a lot to everybody who is willing to improve the wiki! You are awesome!**
+
+----------------------------------------
+_This file is not included in the wiki._
diff --git a/Run-Configuration-Bug.md b/Run-Configuration-Bug.md
diff --git a/Writing-a-plugin.md b/Writing-a-plugin.md
diff --git a/_Footer.md b/_Footer.md
@@ -0,0 +1,4 @@
+**We need your help to improve the wiki!**  
+Head over to [codeoverflow-org/chatoverflow-wiki](https://github.com/codeoverflow-org/chatoverflow-wiki) to edit the wiki and create a pull request.  
+
+**You still need help?** Join our [discord server](https://discord.gg/sX2Gjbs).
diff --git a/_Sidebar.md b/_Sidebar.md
@@ -0,0 +1,21 @@
+### Content
+
+**Usage:**  
+1. [Installation](Installation)  
+2. [Using the CLI](Using-the-CLI)  
+3. [Using the GUI](Using-the-GUI)  
+    1. [Starting the Better REPL](Using-the-GUI#Starting-the-Better-REPL)  
+    2. [Creating a plugin instance](Using-the-GUI#Creating-a-plugin-instance)  
+    3. [Setting plugin requirements](Using-the-GUI#Setting-plugin-requirements)  
+    4. [Adding connectors](Using-the-GUI#Adding-connectors)  
+    5. [Set credentials](Using-the-GUI#Set-credentials)  
+4. [Frequent Issues](Frequent-Issues)  
+    1. [Run Configuration Bug](Frequent-Issues#Run-Configuration-Bug)  
+    2. [Credentials value encrypted with wrong auth key](Frequent-Issues#Credentials-value-encrypted-with-wrong-auth-key)  
+
+**Development:**  
+1. [Writing a plugin](Writing-a-plugin)  
+2. [Adding a new platform source](Adding-a-new-platform-source)  
+3. [Deploy ChatOverflow](Deploy-ChatOverflow)
+4. [Structure](Structure)
+5. [Pluggable migration guide](Pluggable-migration-guide)
diff --git a/Adding-a-new-platform-source.md → development/Adding-a-new-platform-source.md b/Adding-a-new-platform-source.md → development/Adding-a-new-platform-source.md
diff --git a/Deploy-ChatOverflow.md → development/Deploy-ChatOverflow.md b/Deploy-ChatOverflow.md → development/Deploy-ChatOverflow.md
diff --git a/development/Pluggable-migration-guide.md b/development/Pluggable-migration-guide.md
@@ -0,0 +1,31 @@
+If you have updated from 0.2-prealpha to 0.3-prealpha you might notice that your plugins aren't detected by the framework anymore and are also not included in `plugins.sbt` by the sbt fetch task.
+
+This is because as of 0.3-prealpha `Pluggable` got removed and replaced with a xml file called `plugin.xml` in the resources of the plugin. Check the issue at [codeoverflow-org/chatoverflow#41](https://github.com/codeoverflow-org/chatoverflow/issues/41) or the pr at [codeoverflow-org/chatoverflow#91](https://github.com/codeoverflow-org/chatoverflow/pull/91) for more information about this rework.
+
+Here are the required steps to make your plugin compatible with the new format:
+
+1. Delete your class implementing `Pluggable`. Its not used anymore got removed from the api.
+
+2. Create the resources directory at `yourPlugin/src/main/resources`.
+
+3. Create a file at `yourPlugin/src/main/resources/plugin.xml` containing the following: 
+
+   ```xml
+   <plugin>
+       <name>myPluginName</name>
+       <author>sebinside</author>
+       <description>This is a simple plugin for demonstration purposes.</description>
+       <api>
+           <major>3</major>
+           <minor>0</minor>
+       </api>
+       <version>0.3.0</version>
+       <website>https://codeoverflow.org</website>
+       <sourceRepo>https://github.com/codeoverflow-org/chatoverflow-plugins</sourceRepo>
+       <bugtracker>https://github.com/codeoverflow-org/chatoverflow/issues</bugtracker>
+       <license>EPL-2.0</license>
+   </plugin>
+   ```
+
+4. Replace these values with yours. Name, author, api and version are mandatory while the other ones aren't and can be omitted by remove the xml tag. Note that you also may need to adjust the api version numbers if you are running a newer version.
+
diff --git a/Structure.md → development/Structure.md b/Structure.md → development/Structure.md
diff --git a/development/Writing-a-plugin.md b/development/Writing-a-plugin.md
@@ -0,0 +1,104 @@
+**Important: Chat Overflow is still work in progress. So this guide will probably change in the future!**
+
+There are 3 important steps when you want to create and implement a new chat overflow plugin:
+
+1. Create a new plugin project with the commands of the framework
+2. Inspect the `plugin.xml` file
+3. Extend the plugin with own logic
+
+## Create a new plugin project
+
+Use the *Create Plugin* configuration or start the custom task `sbt create` directly. Enter the basic plugin information in the command prompt. This includes mandatory values like the name, author, version and base plugin folder (e.g. `plugins-public`) and some optional values like a description, a website, a link to a source repo, a link to a bug tracker and a license.
+
+The command creates the folder structure of the new plugin and adds a basic build file. Here you can also add custom dependencies. In addition the command generates a basic `plugin.xml` containing all the passed information like name and description and a basic source code file generated in the language of your choice to get you started. Note that currently only Scala and Java are supported.
+
+Next, run the custom task `sbt fetch` to let the framework look for new plugins and update the plugin reference file `plugins.sbt`. If you're using IntelliJ, you can now reload the framework by hand to register the plugin as new and custom project. You should also run `sbt reload` (Yes, both actions have different effects although they shouldn't).
+
+## Inspect the `plugin.xml` file
+
+All the metadata of the plugin like the name and the author of the plugin is saved in a xml file which is located at `src/main/resources/plugin.xml` in the plugin directory. This file gets autogenerated by the create command but in case you need to update a value its good to know where this file is located.
+
+A simple version of the `plugin.xml` file might look like this:
+
+ ```xml
+<plugin>
+    <name>Demonstration</name>
+    <author>sebinside</author>
+    <description>This is a simple plugin for demonstration purposes.</description>
+    <api>
+        <major>3</major>
+        <minor>0</minor>
+    </api>
+    <version>0.3.0</version>
+    <website>https://codeoverflow.org</website>
+    <sourceRepo>https://github.com/codeoverflow-org/chatoverflow-plugins</sourceRepo>
+    <bugtracker>https://github.com/codeoverflow-org/chatoverflow/issues</bugtracker>
+    <license>EPL-2.0</license>
+</plugin>
+ ```
+
+The properties called name, author, api versions and version are mandatory and the framework won't load the plugin if one of these is missing. All others are optional informations for the user. If you don't want to specify a value for those you can just omit them.
+
+The api tag contains the API-Version, you developed the plugin with. These are evaluated in the loading process to ensure that your plugin works with the framework version from the user. You can get these numbers either from `org.codeoverflow.chatoverflow.api.APIVersion` in the api project or in the `build.sbt` also in the api project.
+
+## Extend the Plugin with own logic
+
+The last step is the creation of the plugin class, which contains your own plugin logic. Again the create command has autogenerated a basic class extending `org.codeoverflow.chatoverflow.api.plugin.PluginImpl` in the language of your choice. Such a file might look like this in case of Scala:
+
+```scala
+import org.codeoverflow.chatoverflow.api.plugin.{PluginImpl, PluginManager}
+
+class DemonstrationPlugin(manager: PluginManager) extends PluginImpl(manager) {
+
+  // require more requirements as needed here
+  private val sampleReq = require.input.sample("sampleReq", "Sample requirement", true)
+
+  // you can adjust the loop interval here
+  // loopInterval = 1000;
+
+  /**
+    * The setup method is executed one, when the plugin is started. Do NOT define your requirements in here!
+    */
+  override def setup(): Unit = {
+    log("Initialized Demonstration!")
+  }
+
+  /**
+    * The loop method is executed in loop with a specified interval until the shutdown method is called.
+    * The loop method is NOT executed if a negative loop interval is set.
+    */
+  override def loop(): Unit = {
+    log("Demonstration loop!")
+  }
+
+  /**
+    * The shutdown method should contain logic to close everything.
+    */
+  override def shutdown(): Unit = {
+    log("Shutting down Demonstration!")
+  }
+}
+```
+
+The framework searches for a class implementing `org.codeoverflow.chatoverflow.api.plugin.Plugin` when it tries to load a plugin. `PluginImpl` does this for you and also decreases some other boilerplate. Note that the whole plugin is only allowed to have *exactly* one class implementing `Plugin` otherwise the framework won't load your plugin.
+
+All methods in the generated class are pretty self explaining. The only thing we might need to talk about are *requirements*: These are the way to retrieve data from the outside world and returning information to it. Basically, you can require everything from a single parameter, set by the user, to full access to a users livestream chat.
+
+Thanks to `PluginImpl` a requirements object is already created, meaning you can start adding requirements right away. Here is a example:
+
+```scala
+private val twitchChatInput = require.input.twitchChat("reqTwitch", "A twitch channel", false)
+private val nameToSayHelloTo = require.parameter.string("reqHello", "Your name", false)
+```
+
+This code requires reading-access to a twitch livestream chat and a parameter ("*a name to say hello to"*). Note: You can obviously not specify, which channel the user might choose - but you can be sure, that you will get a working input. This is ensured by the framework.
+
+After this, the last step is the `start` method. And it is as easy as you might think: Just add your own logic now, using the required parameters of your Requirement object. Here is a short example: This code will simply print out all messages from a twitch chat in the console. To access the chat, your required variable is used with the `getValue` method.
+
+```scala
+twitchChatInput.getValue.registerMessageHandler(msg => println(msg))
+```
+
+Of course, you can also add own classes and infrastructure by now - the important steps are done, happy coding!
+
+*One last note: If your testing your plugin the first time, a full reload might be needed. Use the custom task `[Advanced] Full Reload and run ChatOverlfow` to do so. Afters this, you can configure the framework to start your plugin using the [CLI](Using-the-CLI)!*
diff --git a/img/change-requirement.png b/img/change-requirement.png
diff --git a/img/class.png b/img/class.png
diff --git a/img/component.png b/img/component.png
diff --git a/img/create-connector.png b/img/create-connector.png
diff --git a/img/create-plugin.png b/img/create-plugin.png
diff --git a/img/credentials.png b/img/credentials.png
diff --git a/img/login.png b/img/login.png
diff --git a/img/plugin-instances.png b/img/plugin-instances.png
diff --git a/img/plugin-requirements.png b/img/plugin-requirements.png
diff --git a/img/plugin-types.png b/img/plugin-types.png
diff --git a/img/value-encrypted-wrong-key.png b/img/value-encrypted-wrong-key.png
diff --git a/usage/Frequent-Issues.md b/usage/Frequent-Issues.md
@@ -0,0 +1,11 @@
+## Run Configuration Bug 
+Due to IntelliJ version differences and usage on Windows vs. Mac OS, the run configurations show problems, sometimes. Change the *classpath or module* under `Edit configurations...` back to the Chat Overflow root module, and everything should be fine.
+
+## Credentials value encrypted with wrong auth key
+![](img/value-encrypted-wrong-key.png)  
+```
+ERROR configuration.CryptoUtil$  - Your environment does not work with AES256.Please update your java runtime version to at least: 1.8.0_161
+```
+If you see this image or error message you are probably running on an old java version that doesn't work with AES 256 bit encryption.  
+Please follow the instructions from the error message and update java to at least `1.8.0_161`.  
+More information about the issue can be found [on stackoverflow.com](https://stackoverflow.com/questions/3862800/invalidkeyexception-illegal-key-size).