README.md in boty-0.0.4 vs README.md in boty-0.0.6

- old
+ new

@@ -1,31 +1,144 @@ # Boty -Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/boty`. To experiment with that code, run `bin/console` for an interactive prompt. +`Boty` is a utilitary to create bots (at this time, specificaly Slack bots). -TODO: Delete this and the text above, and describe your gem +A bot is this context is a ordinary ruby application, that knows how to receive +messages. Boty will give you a nice way to bind your own logic to specific +messages of your own interest. -## Installation +## Slack Bot Integration<a id="integration" /> -Add this line to your application's Gemfile: +The first thing to do is to create a Slack Bot integration. +Go to `http://[your-company-name].slack.com/services` to add a new one. +In the process an `API Token` will be generated. That will be used in the [next +step](#installation). -```ruby -gem 'boty' +## Installation<a id="installation" /> + +Now you can install `Boty`: + +```sh +$ gem install boty ``` -And then execute: +This will give you an executable `boty`, which ships with a command `help` so +you can know all the stuff that it can do. But the main one is to [create your +new shiny bot](#usage). - $ bundle +## Usage<a id="usage" /> -Or install it yourself as: +In this section you will learn how to create a custom bot application for your +needs, how to configure it to allow the bot say stuff in your slack channels and +finally, will see how to run the bot properly. - $ gem install boty +### Creating a new bot -## Usage +To create a new bot, execute: -TODO: Write usage instructions here +```sh +$ boty new jeeba +``` +Where `jeeba` will be the nickname you give your bot in the [Slack +integration](#integration). + +The command will create a new directory after your bot name (`jeeba` in my +example). Your _bot application_ will live in this directory. Feel free to check +the directory, it will have some ruby files, some directories... it's just an +ordinary ruby application. + +But first, let's see something about the [configurations](#configuration). + +### Configuration<a id="configuration" /> + +When executing the `boty new` command, you will be prompted for the +*company name* and the *bot api key*. + +The information that you enter will be used only locally, so you can experiment +and test (we will see more about the automated ones in this *README*) while +developing your bot. This will be stored in the `.env.local` file on the +recently created dir. + +If you want to understand how this configuration is managed locally, you can +check de [`Dotenv` gem documentation](https://github.com/bkeepers/dotenv), but +you don't need to worry about it. + +### Running locally<a id="running" /> + +After create the new _bot application_ and give the *bot api key*, you can just +enter the new dir and run + +```sh +$ ./bot +``` + +Done! Your bot will be connected to your company Slack through the nickname that +you provided in the [integration](#integration) step. +To see if it's working properly, just go the the slack, in the general channel +(or any other where the bot was invited) and type: + +```sh +@jeeba: ping +``` + +It will respond to you: `pong`. IT'S ALIVE. + +### Deploy on heroku + +But probably what you want is to have your bot running in a server, not in your +machine, right? + +Your bot is created with an example `Procfile` to make it easy to run it on +[Heroku](http://heroku.com) (to give an example). + +Create a new project on Heroku, following their instructions, until they ask you +to do the "deploy" (the `git push heroku master`). + +#### configure the api key + +Now you need to add the configurations that are localy stored on `.env.local`. +The two environment variables on that file are: + + SLACK_COMPANY + SLACK_BOT_API_TOKEN + +The *Heroku* command line tool offers a way to create environment vars in the +server, check +[their documentation](https://devcenter.heroku.com/articles/config-vars). +Today, when as I'm writing the readme, you can use the following commands to set +those two environment variables: + + $ heroku config:set SLACK_COMPANY=your-company-name + $ heroku config:set SLACK_BOT_API_TOKEN=your-bot-integration-api-token + +#### allow process to run + +Heroku will not detect a web application in your bot, so you need to tell them +to run your application as a, well... as a "normal" application. +Go to your heroku dashboard (https://dashboard.heroku.com/apps), find the +application that you have created to your bot. +On the tab _Resources_, find a line with the information: + + your-bot-name bundle exec ./bot + + +Turn on this resource. And done, your bot is up and running! + + +## Adding custom scripts + + **todo: document** + +For now, check the `script/ping.rb` and follow it's leads. + +### Testing your own scripts + + **todo: document**` + +For now, check the `spec/script/ping_spec.rb` and follow it's leads. + ## Development After checking out the repo, run `bin/setup` to install dependencies. You can also run `bin/console` for an interactive prompt that will allow you to experiment. To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org). @@ -36,6 +149,5 @@ ## License The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT). -