slack-ruby-bot-boilerplate 0.1.0

data/Rakefile

@@ -0,0 +1,19 @@
+require 'rubygems'
+require 'bundler'
+require 'bundler/gem_tasks'
+
+Bundler.setup :default, :development
+
+unless ENV['RACK_ENV'] == 'production'
+  require 'rspec/core'
+  require 'rspec/core/rake_task'
+
+  RSpec::Core::RakeTask.new(:spec) do |spec|
+    spec.pattern = FileList['spec/**/*_spec.rb']
+  end
+
+  require 'rubocop/rake_task'
+  RuboCop::RakeTask.new
+
+  task default: %i[rubocop spec]
+end

data/TUTORIAL.md

@@ -0,0 +1,218 @@
+## Production Bot Tutorial
+
+In this tutorial we'll implement [slack-mathbot](https://github.com/dblock/slack-mathbot).
+
+### Introduction
+
+A typical production Slack bot is a combination of a vanilla web server and a websocket application that talks to the [Slack Real Time Messaging API](https://api.slack.com/rtm). The web server is optional, but most people will run their Slack bots on [Heroku](https://dashboard.heroku.com) in which case a web server is required to prevent Heroku from shutting the bot down. It also makes it convenient to develop a bot and test using `foreman`.
+
+### Getting Started
+
+#### Gemfile
+
+Create a `Gemfile` that uses [slack-ruby-bot](https://github.com/slack-ruby/slack-ruby-bot), [sinatra](https://github.com/sinatra/sinatra) (a web framework) and [puma](https://github.com/puma/puma) (a web server). For development we'll also use [foreman](https://github.com/theforeman/foreman) and write tests with [rspec](https://github.com/rspec/rspec).
+
+```ruby
+source 'https://rubygems.org'
+
+gem 'slack-ruby-bot'
+gem 'puma'
+gem 'sinatra'
+gem 'dotenv'
+gem 'celluloid-io'
+
+group :development, :test do
+  gem 'rake'
+  gem 'foreman'
+end
+
+group :test do
+  gem 'rspec'
+  gem 'rack-test'
+  gem 'vcr'
+  gem 'webmock'
+end
+```
+
+Run `bundle install` to get all the gems.
+
+#### Application
+
+Create a folder called `slack-mathbot` and inside of it create `bot.rb`.
+
+```ruby
+module SlackMathbot
+  class Bot < SlackRubyBot::Bot
+  end
+end
+```
+
+#### Commands
+
+Create a folder called `slack-mathbot/commands` and inside of it create `calculate.rb`. For now this calculator will always return 4.
+
+```ruby
+module SlackMathbot
+  module Commands
+    class Calculate < SlackRubyBot::Commands::Base
+      command 'calculate' do |client, data, _match|
+        client.say(channel: data.channel, text: '4')
+      end
+    end
+  end
+end
+```
+
+#### Require Everything
+
+Create a `slack-mathbot.rb` at the root and require the above files.
+
+```ruby
+require 'slack-ruby-bot'
+require 'slack-mathbot/commands/calculate'
+require 'slack-mathbot/bot'
+```
+
+#### Web Server
+
+We will need to keep the bot alive on Heroku, so create `web.rb`.
+
+```ruby
+require 'sinatra/base'
+
+module SlackMathbot
+  class Web < Sinatra::Base
+    get '/' do
+      'Math is good for you.'
+    end
+  end
+end
+```
+
+#### Config.ru
+
+Tie all the pieces together in `config.ru` which creates a thread for the bot and runs the web server on the main thread.
+
+```ruby
+$LOAD_PATH.unshift(File.dirname(__FILE__))
+
+require 'dotenv'
+Dotenv.load
+
+require 'slack-mathbot'
+require 'web'
+
+Thread.abort_on_exception = true
+
+Thread.new do
+  begin
+    SlackMathbot::Bot.run
+  rescue Exception => e
+    STDERR.puts "ERROR: #{e}"
+    STDERR.puts e.backtrace
+    raise e
+  end
+end
+
+run SlackMathbot::Web
+```
+
+### Create a Bot User
+
+In Slack administration create a new Bot Integration under [services/new/bot](http://slack.com/services/new/bot).
+
+![](screenshots/register-bot.png)
+
+On the next screen, note the API token.
+
+#### .env
+
+Create a `.env` file with the API token from above and make sure to add it to `.gitignore`.
+
+```
+SLACK_API_TOKEN=...
+```
+
+### Procfile
+
+Create a `Procfile` which `foreman` will use when you run the `foreman start` command below.
+
+```
+web: bundle exec puma -p $PORT
+```
+
+### Run the Bot
+
+Run `foreman start`. Your bot should be running.
+
+```
+14:32:32 web.1  | Puma starting in single mode...
+14:32:32 web.1  | * Version 2.11.3 (ruby 2.1.6-p336), codename: Intrepid Squirrel
+14:32:32 web.1  | * Min threads: 0, max threads: 16
+14:32:32 web.1  | * Environment: development
+14:32:35 web.1  | * Listening on tcp://0.0.0.0:5000
+14:32:35 web.1  | Use Ctrl-C to stop
+14:32:36 web.1  | I, [2015-07-10T14:32:36.216663 #98948]  INFO -- : Welcome 'mathbot' to the 'xyz' team at https://xyz.slack.com/.
+14:32:36 web.1  | I, [2015-07-10T14:32:36.766955 #98948]  INFO -- : Successfully connected to https://xyz.slack.com/.
+```
+
+### Try
+
+Invite the bot to a channel via `/invite [bot name]` and send it a `calculate` command with `[bot name] calculate 2+2`. It will respond with `4` from the code above.
+
+### Write Tests
+
+#### Spec Helper
+
+Create `spec/spec_helper.rb` that includes the bot files and shared RSpec support from slack-ruby-bot.
+
+```ruby
+$LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..'))
+
+require 'slack-ruby-bot/rspec'
+require 'slack-mathbot'
+```
+
+#### Test the Bot Application
+
+Create a test for the bot application itself in `spec/slack-mathbot/bot_spec.rb`.
+
+```ruby
+require 'spec_helper'
+
+describe SlackMathbot::Bot do
+  def app
+    SlackMathbot::Bot.instance
+  end
+
+  subject { app }
+
+  it_behaves_like 'a slack ruby bot'
+end
+```
+
+#### Test a Command
+
+Create a test for the `calculate` command in `spec/slack-mathbot/commands/calculate_spec.rb`. The bot is addressed by its user name.
+
+```ruby
+require 'spec_helper'
+
+describe SlackMathbot::Commands::Calculate do
+  def app
+    SlackMathbot::Bot.instance
+  end
+
+  subject { app }
+
+  it 'returns 4' do
+    expect(message: "#{SlackRubyBot.config.user} calculate 2+2", channel: 'channel').to respond_with_slack_message('4')
+  end
+end
+```
+
+See [lib/slack-ruby-bot/rspec/support/slack-ruby-bot](lib/slack-ruby-bot/rspec/support/slack-ruby-bot) for other shared RSpec behaviors.
+
+### Deploy
+
+See [DEPLOYMENT](DEPLOYMENT.md) for how to deploy your bot to production.

data/UPGRADING.md

@@ -0,0 +1,226 @@
+Upgrading SlackRubyBot
+======================
+
+### Upgrading to >= 0.12.0
+
+#### Remove any references to `SlackRubyBot::Server#restart!`
+
+We have removed `SlackRubyBot::Server#restart!` since the [`slack-ruby-client`](https://github.com/slack-ruby/slack-ruby-client/blob/master/CHANGELOG.md) now restarts any connection that was not intentionally stopped via `SlackRubyBot::Server#stop!`.
+
+### Upgrading to >= 0.10.4
+
+#### Replace `server.hooks.add` with `server.on`
+
+We have deprecated `SlackRubyBot::Server#hooks` in favor of `SlackRubyBot::Server#on` instance method. All users using `SlackRubyBot::Server#hooks` method should
+change their codebase and use the new method instead. Method signature is not affected.
+
+Example:
+
+```ruby
+  # Given server is an instance of SlackRubyBot::Server
+  #
+  # Before
+  server.hooks.add :hello, Greet.new
+
+  # After
+  server.on :hello, Greet.new
+```
+
+### Upgrading to >= 0.9.0
+
+#### Add giphy to your Gemfile for GIF support
+
+The dependency on the `giphy` gem was dropped and GIFs don't appear by default. If you want GIF support, add `gem 'giphy'` to your **Gemfile**.
+
+You should not need to make any changes if you had already disabled GIFs for your bot.
+
+See [#89](https://github.com/slack-ruby/slack-ruby-bot/pull/89) for more information.
+
+### Upgrading to >= 0.8.0
+
+#### Require a concurrency library
+
+The `faye-websocket` library is no longer required by default. Add either `faye-websocket` or `celluiloid-io` to your `Gemfile` depending on which concurrency implementation you'd like to use. We recommend `celluloid-io` moving forward.
+
+#### Hook::Base was removed, explicitly register any custom hook classes
+
+Hook classes are now handled differently, namely they are explicitly registered into `SlackRubyBot::Server` via a configuration option (`hook_handlers`) or by passing a similar hash later on through the `add_hook_handlers` method. Including Hook classes directly into the server class is no longer needed.
+
+A hook is actioned via a `call` message onto the handler object (this can be anything that responds to that), so you'll need to rename your method.
+
+Finally, you can now register multiple hooks for the same event, so if you had any code to remove default hooks, you'll need to change it so you pass a configuration hash into `Server`
+
+### Upgrading to >= 0.7.0
+
+#### Simplify Match Expression Checking
+
+The regular expression parser for commands will now include a `nil` value for `expression` when an expression is not present. You can therefore no longer rely on checking `match.names.include?('expression')`, instead check `match['expression']`.
+
+#### Remove any bot.auth! calls
+
+SlackRubyBot 0.6.x versions invoked a method called `auth!`, which caused a pre-flight authentication via Slack Web API `auth_test` method and collected a number of properties, such as client and team ID or name. This method has been removed in favor of using data available in the `Slack::RealTime::Client` local store introduced in [slack-ruby-client#54](https://github.com/slack-ruby/slack-ruby-client/issues/54). Remove any explicit calls to this method.
+
+### Upgrading to >= 0.6.0
+
+While entirely compatible with the 0.5.x series, a number of methods have been deprecated and will be removed in the next release.
+
+#### Replace SlackRubyBot::Commands::Base#call with command, operator or match
+
+Prefer `command`, `operator` or `match` with a block instead of implementing a `self.call` method.
+
+Before:
+
+```ruby
+require 'slack-ruby-bot'
+
+class Bot < SlackRubyBot::Bot
+  command 'ping'
+
+  def self.call(client, data, match)
+    ...
+  end
+end
+```
+
+After:
+
+```ruby
+require 'slack-ruby-bot'
+
+class Bot < SlackRubyBot::Bot
+  command 'ping' do |client, data, match|
+    ...
+  end
+end
+```
+
+#### Replace send_message, send_message_with_gif and send_gif with client.say
+
+Use `client.say` instead of `send_message`, `send_message_with_gif` and `send_gif` in commands.
+
+Before:
+
+```ruby
+class Bot < SlackRubyBot::Bot
+ command 'one' do |client, data, match|
+  send_message client, data.channel, 'Text.'
+ end
+
+ command 'two' do |client, data, match|
+  send_message_with_gif client, data.channel, "Text.", 'keyword'
+ end
+
+ command 'three' do |client, data, match|
+  send_gif client, data.channel, 'keyword'
+ end
+end
+```
+
+After:
+
+```ruby
+class Bot < SlackRubyBot::Bot
+ command 'one' do |client, data, match|
+  client.say(channel: data.channel, text: 'Text.')
+ end
+
+ command 'two' do |client, data, match|
+  client.say(channel: data.channel, text: 'Text.', gif: 'keyword')
+ end
+
+ command 'three' do |client, data, match|
+  client.say(channel: data.channel, gif: 'keyword')
+ end
+end
+```
+
+#### For basic bots replace SlackRubyBot::App with SlackRubyBot::Bot and implement commands inline
+
+Before:
+
+```ruby
+module PongBot
+  class App < SlackRubyBot::App
+  end
+
+  class Ping < SlackRubyBot::Commands::Base
+    command 'ping' do |client, data, _match|
+      client.message(text: 'pong', channel: data.channel)
+    end
+  end
+end
+
+PongBot::App.instance.run
+```
+
+After:
+
+```ruby
+class Bot < SlackRubyBot::Bot
+  command 'ping' do |client, data, _match|
+    client.say(text: 'pong', channel: data.channel)
+  end
+end
+
+Bot.run
+```
+
+### Upgrading to >= 0.4.0
+
+This version uses [slack-ruby-client](https://github.com/slack-ruby/slack-ruby-client) instead of [slack-ruby-gem](https://github.com/aki017/slack-ruby-gem).
+
+The command interface now takes a `client` parameter, which is the RealTime Messaging API instance. Add the new parameter to all `call` calls in classes that inherit from `SlackRubyBot::Commands::Base`.
+
+Before:
+
+```ruby
+def self.call(data, match)
+  ...
+end
+```
+
+After:
+
+```ruby
+def self.call(client, data, match)
+  ...
+end
+```
+
+This also applies to `command`, `operator` and `match` blocks.
+
+Before:
+
+```ruby
+command 'ping' do |data, match|
+  ...
+end
+```
+
+After:
+
+```ruby
+command 'ping' do |client, data, match|
+  ...
+end
+```
+
+You can now send messages directly via the RealTime Messaging API.
+
+```ruby
+client.message text: 'text', channel: 'channel'
+```
+
+Otherwise you must now pass the `client` parameter to `send_message` and `send_message_with_gif`.
+
+```ruby
+def self.call(client, data, match)
+  send_message client, data.channel, 'hello'
+end
+```
+
+```ruby
+def self.call(client, data, match)
+  send_message_with_gif client, data.channel, 'hello', 'hi'
+end
+```