This repository has been archived by the owner on Oct 20, 2018. It is now read-only.
-
-
Notifications
You must be signed in to change notification settings - Fork 59
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #14 from abhisekp/fix/update-readme
Update Readme
- Loading branch information
Showing
1 changed file
with
131 additions
and
132 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,151 +1,164 @@ | ||
| # CamperBot! | ||
| [](https://gitter.im/FreeCodeCamp/camperbot) | ||
|
|
||
| [](https://gitter.im/FreeCodeCamp/camperbot?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) | ||
| This is a full featured bot for [Gitter.im/FreeCodeCamp](https://gitter.im/orgs/FreeCodeCamp/rooms) chat rooms. | ||
|
|
||
| This is a full featured bot for Gitter. | ||
| Main features: | ||
| - integration with github Wiki | ||
| - search, find | ||
| **Main features:** | ||
| - integration with github FCC wiki | ||
| - `find` (alias `explain`) command to show wiki pages | ||
| - wrapper for commands | ||
|
|
||
|
|
||
| The CamperBot is integrated into FreeCodeCamp | ||
|
|
||
| Join us in Gitter to discuss! | ||
| https://gitter.im/FreeCodeCamp/camperbot | ||
|
|
||
| # Introducing CamperBot! | ||
|
|
||
| CamperBot is a full featured bot for Gitter.im developed to integrate with the chatrooms [for FreeCodeCamp, the largest online bootcamp in the world,](https://twitter.com/FreeCodeCamp/status/627338604134559744) where he supports more than 30,000 users in the main chatroom. | ||
| The CamperBot is integrated into various FreeCodeCamp chat rooms. | ||
|
|
||
| Join us in [Gitter.im/FreeCodeCamp/camperbot](https://gitter.im/FreeCodeCamp/camperbot) to discuss about camperbot development! | ||
|
|
||
| Test the CamperBot in [Gitter.im/FreeCodeCamp/camperbotPlayground](https://gitter.im/FreeCodeCamp/camperbotPlayground) room. | ||
|
|
||
| ## Contents | ||
| - [Introducing CamperBot!](https://github.com/FreeCodeCamp/camperbot/#introducing-camperbot) | ||
| - [Installation instructions](https://github.com/FreeCodeCamp/camperbot/#installation-instructions) | ||
| - [Mac / Linux](https://github.com/FreeCodeCamp/camperbot/#mac--linux) | ||
| - [Windows](https://github.com/FreeCodeCamp/camperbot/#windows) | ||
| - [Getting your own appID](https://github.com/FreeCodeCamp/camperbot/#getting-your-own-appid) | ||
| - [Running tests](https://github.com/FreeCodeCamp/camperbot/#running-tests) | ||
| - [Wiki Content](https://github.com/FreeCodeCamp/camperbot/#wiki-content) | ||
| - [System Overview](https://github.com/FreeCodeCamp/camperbot/#system-overview) | ||
| - [Room Joins](https://github.com/FreeCodeCamp/camperbot/#dataroomdatajs) | ||
| - [Bot Commands](https://github.com/FreeCodeCamp/camperbot/#libbotbotcommandsjs) | ||
| - [Wiki Data](https://github.com/FreeCodeCamp/camperbot/#kbasejs) | ||
| - [Room Messages](https://github.com/FreeCodeCamp/camperbot/#roommessagesjs) | ||
| - [Create own bot](https://github.com/FreeCodeCamp/camperbot/#how-to-add-a-new-bot-command) | ||
| - [Bot command details](https://github.com/FreeCodeCamp/camperbot/#more-detail-on-how-commands-are-found-and-called) | ||
| - [Environment Notes](https://github.com/FreeCodeCamp/camperbot/#environment-notes) | ||
| - [Contributing](https://github.com/FreeCodeCamp/camperbot/#contributing) | ||
| - [Chat with us!](https://github.com/FreeCodeCamp/camperbot/#chat-with-us) | ||
| - [Credits](https://github.com/FreeCodeCamp/camperbot/#credits) | ||
|
|
||
| ## Introducing CamperBot! | ||
| CamperBot is a full featured chat bot for [Gitter.im](https://gitter.im) developed to integrate with the chat rooms for [FreeCodeCamp — the largest online coding bootcamp in the world](http://www.freecodecamp.com/), where it serves more than 60,000 campers. | ||
|
|
||
| ### Github Wiki Search | ||
|
|
||
| You can search for articles in a projects github wiki | ||
| You can search for articles in a projects github wiki | ||
|
|
||
| ### Share wiki summaries in chat | ||
|
|
||
| Use `explain` to pull a wiki summary right into the chat: | ||
| Use `explain` to pull a wiki summary right into the chat: | ||
|  | ||
|
|
||
| ### Points system | ||
|
|
||
| Allow your users to send points to each other to say 'thanks @friend' | ||
| Allow your users to send points to each other to say `thanks @username` | ||
|  | ||
|
|
||
| ### Fixed messages | ||
|
|
||
| Based on scannable expressions, send messages into the chat. | ||
|
|
||
| ### Extensible | ||
|
|
||
| Custom functions can easily be added. Check the [System overview](https://github.com/dcsan/gitterbot#system-overview) | ||
| or contact [RIKAI Labs](mailto:[email protected]). | ||
| Custom functions can easily be added. Check the [System Overview](https://github.com/FreeCodeCamp/camperbot#system-overview) | ||
|
|
||
| ## Installation instructions | ||
|
|
||
| To run GitterBot, you need [Node.js](https://nodejs.org/) before downloading the app. | ||
|
|
||
| To run camperbot, you need [Node.js](https://nodejs.org/). | ||
|
|
||
| ### Mac / Linux | ||
| To install Node, [follow the instructions here](http://blog.teamtreehouse.com/install-node-js-npm-mac) | ||
|
|
||
| - To install Node, [follow the instructions here](http://blog.teamtreehouse.com/install-node-js-npm-mac) | ||
|
|
||
| - To make your file changes update the local server automatically, install nodemon (you may need sudo) | ||
|
|
||
| sudo npm install -g nodemon | ||
| - To make your the local server automatically watch for file changes, install "nodemon" (you may need `sudo`) | ||
| ```sh | ||
| sudo npm install -g nodemon | ||
| ``` | ||
|
|
||
| - To download the app, clone the repository the bot is in: | ||
|
|
||
| git clone [email protected]:dcsan/gitterbot.git | ||
| ```sh | ||
| git clone https://github.com/FreeCodeCamp/camperbot.git | ||
| ``` | ||
|
|
||
| - Run the following commands to run the app: | ||
|
|
||
| cd gitterbot | ||
| cd nap | ||
| cp dot-EXAMPLE.env dot.env | ||
| nodemon app.js | ||
| ```sh | ||
| cd camperbot | ||
| cd nap | ||
| cp dot-EXAMPLE.env dot.env | ||
| nodemon app.js | ||
| ``` | ||
|
|
||
| - That's it! The app should be running at [http://localhost:7891](http://localhost:7891). | ||
|
|
||
| You can now chat to your CamperBot via Gitter at | ||
| You can now chat to your bot via [Gitter.im](https://gitter.im) at | ||
| [https://gitter.im/demobot/test](https://gitter.im/demobot/test) | ||
|
|
||
|
|
||
| ### Windows | ||
|
|
||
| To install Node.js on Windows, [follow these instructions](http://blog.teamtreehouse.com/install-node-js-npm-windows). | ||
|
|
||
| - To make your file changes update the local server automatically, install nodemon in an administrator console. | ||
|
|
||
| npm install -g nodemon | ||
|
|
||
| - To make your the local server automatically watch for file changes, install "nodemon" in an administrator console. | ||
| ```sh | ||
| npm install -g nodemon | ||
| ``` | ||
|
|
||
| - To download the app, clone the repository the bot is in: | ||
|
|
||
| git clone https://github.com/dcsan/gitterbot.git | ||
| ```sh | ||
| git clone https://github.com/FreeCodeCamp/camperbot.git | ||
| ``` | ||
|
|
||
| - Run the following commands to run the app: | ||
|
|
||
| cd gitterbot | ||
| cd nap | ||
| ren dot-EXAMPLE.env dot.env | ||
| nodemon app.js | ||
| ```sh | ||
| cd gitterbot | ||
| cd nap | ||
| copy dot-EXAMPLE.env dot.env | ||
| nodemon app.js | ||
| ``` | ||
|
|
||
| - That's it! The app should be running at [http://localhost:7891](http://localhost:7891). | ||
|
|
||
| You can now chat to your gitterbot via Gitter at | ||
| You can now chat to your bot via [Gitter.im](https://gitter.im) at | ||
| [https://gitter.im/demobot/test](https://gitter.im/demobot/test) | ||
|
|
||
| ### Getting your own appID | ||
| The `dot.env` file you copied above contains login info. This is using the shared "demobot" account so you may find yourself in a chatroom with other people using the same ID! | ||
|
|
||
| To setup your own gitter login info, you should create your own Gitter API key on their developer site, and replace the info in that `.env` file. Get your own API keys for gitter from: [https://developer.gitter.im/apps](https://developer.gitter.im/apps) | ||
|
|
||
| # Getting your own appID | ||
| The `dot.env` file you copied above contains login info. This is using shared "demobot" account so you may find yourself in a chatroom with other people using the same ID! | ||
|
|
||
| To setup this up and use your own gitter login info, you should create your own Gitter API key on their developer site, and replace the info in that `.env` file. Get your own API keys for gitter from: [https://developer.gitter.im/apps](https://developer.gitter.im/apps) | ||
|
|
||
| For more settings info, checkout the `AppConfig.js` and `RoomData.js` files. These define which rooms the bot will listen in to. You can ping us in the Dev Chatroom if you have problems [gitterbot chatroom](https://gitter.im/dcsan/gitterbot) . | ||
|
|
||
| For more settings info, checkout the `AppConfig.js` and `RoomData.js` files. These define which rooms the bot will listen in to. | ||
|
|
||
| # Running tests | ||
| You may chat with us in the CamperBot Dev chat room if you have problems. [camperbot chatroom](https://gitter.im/FreeCodeCamp/camperbot). | ||
|
|
||
| ### Running tests | ||
| There are other commands in `bin` for running tests with the right config files etc | ||
| To run the tests with the right configs | ||
|
|
||
| $ bin/test.sh | ||
|
|
||
| ```sh | ||
| bin/test.sh | ||
| ``` | ||
|
|
||
| # Wiki Content | ||
| ## Wiki Content | ||
| The wiki content is pulled in from FCC's wiki using a git submodule. But then we just copy it and commit it back to the main app as submodules are nasty to deal with on production servers. | ||
|
|
||
| bin/wiki-update.sh | ||
|
|
||
| ```sh | ||
| bin/wiki-update.sh | ||
| ``` | ||
|
|
||
| # System Overview | ||
| ## System Overview | ||
|
|
||
| ### data/RoomData.js | ||
| The list of rooms your bot is going to join. | ||
| Very starting your own bot, create a test room to enter and debug with. | ||
|
|
||
| To start with create your own bot, a test room to enter and debug in. | ||
| This needs to be changed so you would only join your own rooms, otherwise developers will get into a situation where everyone is joining the same rooms and the bots go crazy talking to each other! | ||
|
|
||
| ### lib/bot/BotCommands.js | ||
| This is where you add things that the bot can do. Some commands are broken into separate files such as `cmds/thanks` and `cmds/about`. | ||
| This is where you add things that the bot can do. Some commands are broken into separate files such as `cmds/thanks.js` and `cmds/update.js`. | ||
| Each command gets a `input` which is a blob of data including what the user entered, and a bot instance. | ||
|
|
||
| ### KBase.js | ||
| The Knowledge base. This is an interface to all the data in the wiki. | ||
|
|
||
|
|
||
| ### RoomMessages.js | ||
|
|
||
| This is for static messages that are fired based on regex matches. If you just want to add some basic responses, this is the place to edit. | ||
|
|
||
| ### How to add a new Bot Command | ||
|
|
||
| Look at BotCommands `echo` function. This is an example of a command being called. Anytime a user types a line starting with `echo` that will get passed to this function in input. | ||
| Look at `BotCommands`, `echo` function. This is an example of a command being called. Anytime a user types a line starting with `echo` that will get passed to this function in input. | ||
|
|
||
| ```js | ||
| echo: function(input, bot) { | ||
| var username = input.message.model.fromUser.username; | ||
| return "@" + username + " said: " + input.message.model.text; | ||
| }, | ||
| echo: function(input, bot) { | ||
| var username = input.message.model.fromUser.username; | ||
| return "@" + username + " said: " + input.message.model.text; | ||
| } | ||
| ``` | ||
|
|
||
| The input object contains `keyword` and `params` fields. If you type `echo this` you'll get | ||
|
|
@@ -158,86 +171,72 @@ The input object contains `keyword` and `params` fields. If you type `echo this` | |
| } | ||
| ``` | ||
|
|
||
| From any command you just return the new string you want to output. | ||
| From any command you just return the new string you want to output. | ||
| So you can add new commands with this knowledge. | ||
|
|
||
| ### More detail on how commands are found and called | ||
|
|
||
| In GBot.js | ||
| In `GBot.js` | ||
|
|
||
| if (input.command) { | ||
| // this looks up a command and calls it | ||
| output = BotCommands[input.keyword](input, this); | ||
| } else { | ||
| ```js | ||
| if (input.command) { | ||
| // this looks up a command and calls it | ||
| output = BotCommands[input.keyword](input, this); | ||
| } else { | ||
| ``` | ||
| BotCommands is a list of functions, eg | ||
| `BotCommands` is a list of functions. E.g. | ||
| BotCommands.thanks = function() { ... } | ||
| ```js | ||
| BotCommands.thanks = function() { ... } | ||
| ``` | ||
| where `input.keyword` is `thanks` then | ||
| `BotCommands[input.keyword]` is like saying `BotCommands.thanks()` | ||
| so then the params get also added in `(input, this)` so its | ||
| ```js | ||
| BotCommands[input.keyword](input, this); | ||
| //becomes | ||
| BotCommands.thanks(input, bot); | ||
| ``` | ||
| BotCommands[input.keyword](input, this); | ||
| //becomes | ||
| BotCommands.thanks(input, bot); | ||
|
|
||
| All of the botCommands expect these two params eg in thanks.js | ||
|
|
||
| var commands = { | ||
| thanks: function (input, bot) { | ||
| All of the bot commands expect these two params. E.g. in `thanks.js` | ||
| ```js | ||
| var commands = { | ||
| thanks: function (input, bot) { | ||
| ``` | ||
| In `RoomMessages.js` we also have a table of regex and matching functions, and may switch all to just use this method in future. Would you like to help? | ||
| In `RoomMessages.js` we also have a table of regex and matching functions. | ||
| ``` | ||
| { | ||
| regex: /\bth?a?n?[xk]s?q?\b/gim, | ||
| func: BotCommands.thanks | ||
| } | ||
| ```js | ||
| { | ||
| regex: /\bth?a?n?[xk]s?q?\b/gim, | ||
| func: BotCommands.thanks | ||
| } | ||
| ``` | ||
| > We may switch all to just use this method in future. Would you like to help? | ||
| ## environment notes | ||
| ## Environment Notes | ||
| ### wiki data | ||
| we use git submodules for some wiki data. to get these submodules you would do: | ||
|
|
||
| git submodule init | ||
| git submodule update | ||
| We use git submodules for some wiki data. to get these submodules you would do: | ||
|
|
||
| ### ES6 and iojs | ||
|
|
||
| We downgraded the app to use basic node, so it should run even without iojs. | ||
| But its recommended to run on iojs rather than the older node (until they merge the projects) | ||
| To do this: | ||
|
|
||
|
|
||
| ```bash | ||
| # ubuntu | ||
| sudo apt-get upgrade | ||
| sudo apt-get install build-essential | ||
| ``` | ||
|
|
||
| we're using n to update node [article](http://davidwalsh.name/upgrade-nodejs) | ||
| We use n to manage iojs and node: | ||
| ``` | ||
| sudo npm install -g n | ||
| sudo n io latest | ||
| iojs -v | ||
| // should be at least v2.4.0 | ||
| ```sh | ||
| git submodule update --remote --checkout --init --recursive | ||
| ``` | ||
| # Contributing | ||
| have a look at the [HelpWanted](https://github.com/dcsan/gitterbot/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) label issues and consider making some first steps! | ||
| the labels, P1 = priority one, and 'S' means a small task, so good places to start. | ||
| https://waffle.io/dcsan/gitterbot | ||
| ## Contributing | ||
| Have a look at the [HelpWanted](https://github.com/FreeCodeCamp/camperbot/issues?q=is%3Aopen+label%3A%22help+wanted%22) label issues and consider making some first steps! | ||
| The labels, P1 = priority one, and 'S' means a small task, so good places to start. | ||
| # Chat to us! | ||
| ## Chat with us! | ||
| Chat with us in the [camperbot chatroom](https://gitter.im/FreeCodeCamp/camperbot) if you get stuck. | ||
| Ping me @dcsan in the [gitterbot chatroom](https://gitter.im/dcsan/gitterbot) if you get stuck. | ||
| ## Credits | ||
| [@dcsan](https://github.com/dcsan) — [RIKAI Labs](mailto:[email protected]) (**Founder**) | ||