maily_herald 0.8.0 → 0.9.1

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    ZjIwNzFmNTFiM2E1MzI0NGM0MjkxZDQyNTk2MDdkY2IzMmE1YzBjNA==
+    OTc4OTYyZGUxOTM1ZGNiY2MwYWQxMjYwZjFkYjE0NDAzMTUyMTI5Mw==
   data.tar.gz: !binary |-
-    YzBlMTQ1Mzk0ZDEzYTg5N2FhYTlmYjQ3ZGMzY2E0NTZmMGU1NTkzMQ==
+    NmNhNjYyZGI2ZDE2MzcxN2JlYmFkZGVmMzMyZjhhZDQ5ZDhhYzU2YQ==
 SHA512:
   metadata.gz: !binary |-
-    ZmViMzhiN2IzMzg1NWQ0NzI0MjdlMTg3YzI0ZmZlNzU5MjY4NTdjNDJlYTM5
-    NThhY2Q4NGRlZjYwNjBhNDYyYTFkMDE2NTZjZjVhOWFlZmU5YTAwY2ZlZjhm
-    MjU2ZDg5OTZlNWEzZDk3ZjdjM2Q0YzU0Y2RmOGViNmUzNmEzMTA=
+    NTI5ZTVmNTI5YjRjNmUwNmVlZWEwNWFkNzg0NzI4YWZjN2Y0M2JlN2NkNzM0
+    M2EwZjljNjFiZjc3MzA3YWE5MmZkMWZjOWRhMmE2MGUyZjMyMTMxYTVhODc5
+    YTQ1M2RlZmQ5MDJlNTJiYTkyZGRlYzgzOTg0ZmUwMGE5ODQ4NWU=
   data.tar.gz: !binary |-
-    ODhiYzU0N2Q4YTgyNGZhNTg1OWI2NTE1NzA2NmRmODlkNGUyNjE2ODY5ZWU4
-    YjcwMDkyZmNlYzhhOGQ3NWNmYWE4N2I3YjUyZjdlMjFjNjY1Nzg3YTU4YTFi
-    YmI2MTRlNjc1ODNlYzNiNWU2MTNiNjhlODkzY2YxOGVjOTlmYTU=
+    Yjk1MjcxNjY5N2Q5ZWMyZDY2ZTFiY2FiMzYzMTNiMGRkMTU4MmFjMjQ4YWE5
+    NTFjMDBjZDE2ZmZhZWQ4YTM2OGUyNWIyZTE0NDM4MjM2NDc0NjNhYmVlMTNk
+    NTM5MTM0YzkwNzcwZWFkZDNlZTQ4Y2RiMjgxNzU0OThmMjBjNjI=

data/.gitignore

@@ -6,6 +6,7 @@ spec/dummy/log/*.log
 spec/dummy/tmp/
 spec/dummy/.sass-cache
 coverage/*
+doc/*
 dump.rdb
 tmp
 *.gem

data/.travis.yml

@@ -0,0 +1,3 @@
+script: 
+  - RAILS_ENV=test bundle exec rake db:setup
+  - bundle exec rspec

data/Gemfile

@@ -4,5 +4,3 @@ gemspec
 
 # jquery-rails is used by the dummy application
 gem "jquery-rails"
-
-gem 'debugger'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    maily_herald (0.0.1)
+    maily_herald (0.9.0)
       liquid (~> 2.6.1)
       rails (> 3.2)
       sidekiq (~> 2.17.8)
@@ -41,15 +41,8 @@ GEM
     celluloid (0.15.2)
       timers (~> 1.1.0)
     coderay (1.1.0)
-    columnize (0.8.9)
-    connection_pool (2.0.0)
+    connection_pool (2.2.0)
     database_cleaner (1.3.0)
-    debugger (1.6.8)
-      columnize (>= 0.3.1)
-      debugger-linecache (~> 1.2.0)
-      debugger-ruby_core_source (~> 1.3.5)
-    debugger-linecache (1.2.0)
-    debugger-ruby_core_source (1.3.5)
     diff-lcs (1.2.5)
     docile (1.1.3)
     erubis (2.7.0)
@@ -76,7 +69,7 @@ GEM
       railties (>= 3.0, < 5.0)
       thor (>= 0.14, < 2.0)
     json (1.8.1)
-    liquid (2.6.1)
+    liquid (2.6.2)
     listen (2.7.7)
       celluloid (>= 0.15.2)
       rb-fsevent (>= 0.9.3)
@@ -122,8 +115,8 @@ GEM
     rdoc (3.12.2)
       json (~> 1.4)
     redcarpet (3.2.2)
-    redis (3.1.0)
-    redis-namespace (1.5.1)
+    redis (3.2.1)
+    redis-namespace (1.5.2)
       redis (~> 3.0, >= 3.0.4)
     rspec (3.0.0)
       rspec-core (~> 3.0.0)
@@ -181,7 +174,6 @@ PLATFORMS
 
 DEPENDENCIES
   database_cleaner
-  debugger
   factory_girl_rails
   guard
   guard-rspec

data/README.md

@@ -1,17 +1,20 @@
 # MailyHerald
 
-MailyHerald is a Ruby on Rails gem that helps you sending and managing your mailings. Think of Maily as a self-hosted Mailchimp alternative you can easily integrate with your site. MailyHerald is great both for email marketing and conducting daily stream of notifications you send to your users.
+![MailyHerald with its Web UI](./doc/webui.png)
+
+MailyHerald is a Ruby on Rails gem that helps you send and manage your application mailings. Think of Maily as a self-hosted Mailchimp alternative you can easily integrate into your site. MailyHerald is great both for email marketing and conducting the daily stream of notifications you send to your users.
 
 With MailyHerald you can send:
-* one-time mailings (i.e. welcome emails, special offers),
+* ad-hoc mailings - arbitrary emails sent to one or more users at a given point in time (i.e. password reset instructions, special offers, announcements),
+* one-time mailings (i.e. account activation, welcome emails),
 * periodical mailings (i.e. weekly notifications, reminders),
-* mailing sequences - multiple ordered emails delivered with certain delays since specific point in time (i.e. onboarding emails, site feature overview).
+* mailing sequences - multiple ordered emails delivered with certain delays from a specific point in time (i.e. onboarding emails, site feature overview, reminders).
 
-Maily keeps track of user subscriptions and allow them to easily opt out. You can define who receives which emails and specify conditions that control delivery. All deliveries are tracked and logged. Periodical and Sequence mailing deliveries are scheduled individually for each recipient.
+Maily keeps track of user subscriptions and allows them to easily opt out. You can define who receives which emails and specify conditions that control delivery. All mailing deliveries are scheduled individually for each recipient, tracked and logged.
 
-Maily seamlessly integrates with your app. It can use your regular Mailers or you can build ad-hoc mailings with [Liquid](http://liquidmarkup.org/) markup templates. 
+Maily seamlessly integrates with your app. It can use your regular Action Mailers or you can build email contents with [Liquid](http://liquidmarkup.org/) markup templates.
 
-Core Maily features are accessible for Rails programmers via API. Apart from that, Maily has a nice web UI provided by separate [maily_herald-webui](https://github.com/Sology/maily_herald-webui) gem.
+Core Maily features are accessible for Rails programmers via the API. Apart from that, Maily has a nice Web UI provided by a separate [maily_herald-webui](https://github.com/Sology/maily_herald-webui) gem.
 
 ## Requirements
 
@@ -19,7 +22,7 @@ Both Ruby on Rails 3.2 and 4 are supported.
 
 ## Installation
 
-Simply just
+Simply just run
 
     gem install maily_herald
 
@@ -32,72 +35,72 @@ or put in your Gemfile
 * Designed for Ruby on Rails
 * Self-hosted
 * Seamless and flexible integration
-* Asynchronous processing
-* Individual delivery scheduling 
-* Great both for developers (API) and end-users (Web UI) 
-* Ad-hoc email templating using [Liquid](http://liquidmarkup.org/) syntax
-* Three different mailing types
+* Asynchronous email processing
+* Per-recipient delivery scheduling
+* Great both for developers (API) and end users (Web UI)
+* On-the-fly email templating using [Liquid](http://liquidmarkup.org/) syntax
+* Four different mailing types
 * User-friendly subscription management i.e. via automatic & personal opt-out links
 * Correspondence logging
-* Mailing conditions
+* Delivery conditions
 
 ## Development state
 
-MailyHerald is relatively young piece of software and can't be considered stable. Although it has been deployed to few production environments for quite some time now, we can't guarantee it will suite your needs too.
+MailyHerald is a relatively young piece of software and it has been deployed in a few different production environments.
 
-If you decide to use it, please tell us what you think about it, post some issues on GitHub etc. We're waiting for your feedback.
+If you decide to use it, please tell us what you think about it. You can post some issues on GitHub or email us directly. We're waiting for your feedback.
 
 Here are some things we would like to implement in the future:
 
-* better mailing scheduling,
 * message analytics,
 * link tracking,
-* better Web UI,
+* fetching bounces from email service (Amazon SES, Mandrill, Sendgrid etc.),
+* better templating,
 * _put your beloved feature here_.
 
 ## How it works
 
-There are few key concepts that need to be explained in order to understand how Maily works. Some of them are similar to what you might know form other conventional email marketing software. Others come strictly from Ruby on Rails world.
+There are a few key concepts that need to be explained in order to understand how Maily works. Some of them are similar to what you might know from other conventional email marketing software. Others come strictly from the Ruby on Rails world.
 
 **Entities**
 
-Entities are basically your mailing recipients. They will be probably represented in your application by `User` model.
+Entities are your mailing recipients. They will probably be represented in your application by `User` model.
 
 **Mailings**
 
-You usually send single emails to your users - one at a time. Mailing is a bunch of emails sent out to many users. MailyHerald allows you to send three types of Mailings: one-times, periodicals and sequences.
+You usually send single emails to your users, one at a time. Mailing is a bunch of emails sent out to many users. MailyHerald allows you to send four types of Mailings: ad-hoc, one-times, periodicals and sequences.
 
 **Contexts**
 
-Maily Contexts are abstraction layer for accessing collections of entities and their attributes. 
+Maily Contexts provide a layer of abstraction for accessing collections of entities and their attributes.
 
 There are three main things that Contexts do:
 
-* They define sets of entities via Rails scopes (i.e. `User.activated` meaning all application users that activated their accounts). 
+* They define sets of entities via standard Rails scopes (i.e. `User.activated` meaning all application users that activated their accounts).
 * They specify destination email addresses for entities (i.e. you can define that `User#email` method returns email address or specify a custom proc that does that).
-* They specify additional entity attributes that can be used inside Mailing templates, conditions etc. (basically - attributes accessible via Liquid).
+* They specify additional entity attributes that can be used inside Mailing templates, conditions etc. (essentially, any attribute accessible via Liquid).
 
 **Lists and Subscriptions**
 
-Lists are sets of entities that receive certain mailings. Entities are added to Lists by creating Subscriptions. It is entirely up to you how you manage subscriptions in application. Typically, you put some checkbox in user's profile page that subscribes and unsubscribes them from mailing lists.
+Lists are sets of entities that receive certain mailings. Entities are added to Lists by creating Subscriptions. It is entirely up to you how you manage subscriptions in the application. Typically, you would put a checkbox in the user's profile page which subscribes and unsubscribes them from mailing lists.
 
-Each Subscription has it's unique token allowing users to be provided with one click opt-out link.
+Each Subscription has a unique token allowing users to be provided with one-click opt-out links.
 
 **Mailers**
 
-Mailers are standard way of sending emails in Rails applications. MailyHerald hooks into ActionMailer internals and allows you to send Mailings just like you send your regular emails. All you need to do is inherit `MailyHerald::Mailer` in your Mailer. 
+Mailers are the standard way of sending emails in Rails applications. MailyHerald hooks into ActionMailer internals and allows you to send Mailings just like you send your regular emails. All you need to do is inherit `MailyHerald::Mailer` in your Mailer.
 
-There's also a possibility to send Mailings without using any of your custom Mailers. `MailyHerald::Mailer` is in this case used implicitly; email body and subject is stored directly in your Mailing definition as a Liquid template. Liquid gives you access to entity attributes defined in the Context. This way of creating Mailings is especially useful within Web UI where you can build new Mailing by just typing its template.
+There's also a possibility to send Mailings without using any of your custom Mailers. `MailyHerald::Mailer` is in this case used implicitly; email body and subject is stored directly in your Mailing definition as a Liquid template. Liquid gives you access to entity attributes defined in the Context. This way of creating Mailings is especially useful within the Web UI where you can build new Mailing by simply typing in its template.
 
 **Delivery**
 
-MailyHerald uses great gem [Sidekiq](http://sidekiq.org/) to process deliveries in the background. This applies to Periodical and Sequence Mailings - their delivieries are scheduled individually for each entity on the subscription list. 
+MailyHerald uses the great gem [Sidekiq](http://sidekiq.org/) to process deliveries in the background. This applies to all kinds of Mailings - their deliveries are scheduled individually for each entity on the subscription list.
 
-Maily needs to check periodically for scheduled mailings and if their time come - queue them for delivery. This is job for MailyHerald Paperboy - tiny daemon that runs in the background and check the schedules. It is essential to make you periodical and sequence mailings work.
+Maily checks periodically for scheduled mailings, and then the time comes, queues them for delivery. This is the job of MailyHerald Paperboy - a tiny daemon that runs in the background and checks the schedules. It is essential to make your mailings work. 
 
 ## Usage
 
-Let's assume your entities are your `User` model objects. Read on in order to find out how to start with Maily.
+Let's assume your entities are your `User` model objects. Read on in order to find out how to get started with Maily.
 
 ### Migrations
 
@@ -110,9 +113,10 @@ rake db:migrate
 
 ### Defaults (optional)
 
-In some cases, you need to specify default `from` and `host` mailer options in order to ensure proper email rendering:
+In some cases, you need to specify default `from` and `host` mailer options in your application in order to ensure proper email rendering:
 
 ```ruby
+# config/application.rb
 config.action_mailer.default_options = { from: "hello@mailyherald.org" }
 config.action_mailer.default_url_options = { host: "mailyherald.org" }
 
@@ -120,7 +124,7 @@ config.action_mailer.default_url_options = { host: "mailyherald.org" }
 
 ### Initializer
 
-Generate and setup an initializer.
+Generate an initializer:
 
 ```ruby
 rails g maily_herald:install
@@ -139,7 +143,7 @@ There are few things you need to put there.
 
 **Set up your context**
 
-Say for example, you want to deliver your mailings to all your active users:
+Say, for example, you want to deliver your mailings to all your active users:
 
 ```ruby
 config.context :active_users do |context|
@@ -153,7 +157,7 @@ end
 
 **Set up your lists**
 
-Following means that all users in `:active_users` context scope can be subscribed to `:newsletters` list.
+The following means that all users in the `:active_users` context scope can be subscribed to the `:newsletters` list.
 
 ```ruby
 config.list :newsletters do |list|
@@ -161,34 +165,110 @@ config.list :newsletters do |list|
 end
 ```
 
+MailyHerald lists are opt-in lists. They are empty by default, so make sure to add entities to them, i.e. by using `MailyHerald.subscribe` method.
+
 **Set up your mailings**
 
 ```ruby
 config.one_time_mailing :hello do |mailing|
   mailing.title = "Hello mailing"
-  mailing.context_name = :active_users
+  mailing.list = :notifications
   mailing.mailer_name = "UserMailer"
+  mailing.start_at = Proc.new{|user| user.created_at + 1.hour}
   mailing.enable # mailings are disabled by default
 end
 
 config.periodical_mailing :weekly_newsletter do |mailing|
   mailing.title = "Weekly newsletter"
-  mailing.context_name = :active_users
+  mailing.list = :newsletters
   mailing.mailer_name = "UserMailer"
+  mailing.start_at = Proc.new{|user| user.created_at + 1.week}
+  mailing.period = 1.week
+  mailing.enable
+end
+```
+
+**Configuration locking**
+
+By default, all contexts, lists and mailings initialized inside `MailyHerald.setup` block are locked and cannot be edited at runtime. This constraint is enforced to maintain the nature of RoR application initializer files. Things set up in the initializer should always be read-only because the initializer is executed every time the application spawns.
+
+If you need to set up mailings programmatically and make them unlocked, don't simply use `MailyHerald.setup`. Instead, use methods from the `MailyHerald` class directly. You can then enter your code, i.e. in a DB seed file or a rake task.
+
+You would typically put your `MailyHerald.setup` block in the Maily initializer file. Keep in mind that this file is evaluated every time Rails boots up, so changes made there (i.e. new mailings added) will be reflected at next application launch.
+
+### Different mailing types
+
+**AdHocMailing** is the most similar to regular Ruby on Rails emails sent using ActionMailer. The only difference is that their delivery is handled by Maily and thus logged and optionally backgrounded. 
+
+**OneTimeMailing** deliveries are performed only once to a single recipient at a scheduled delivery time. It is fully automatic and its delivery can't be manually triggered. OneTimeMailing schedules are created based on the `start_at` attribute individually for each recipient.
+
+**PeriodicalMailing** handles multiple, periodical email deliveries to individual recipients. It is also automatic. Apart from the `start_at` attribute, it also uses a `period` which defines the time distance between consecutive deliveries.
+
+**Sequence** allows you to send multiple different mailings to a given entity with various time delays. It is achieved by defining SequenceMailings associated to a Sequence with delivery delays stored in their `absolute_delay` attributes. A mailing delivery delay is calculated from a point in time defined in Sequence's `start_at` attribute (similar to PeriodicalMailing).
+
+### Procs and Liquid syntax
+
+Mailing attributes such as `start_at` and `conditions` can be defined programmatically as procs or as a string using Liquid syntax. Here's an example of those two cases:
+
+```ruby
+# Using Proc:
+mailing.start_at = Proc.new{|user| user.created_at + 5.minutes}
+
+# Using Liquid:
+mailing.start_at = "user.created_at | plus: 5, 'minutes'"
+```
+
+Liquid syntax is obviously more convenient for non-programmers (and can be safely used i.e. in WebUI) but requires some additional setup inside Maily Context. Context attributes available within Liquid templates have to be defined:
+
+```ruby
+config.context :all_users do |context|
+  context.scope {User.all}
+  context.destination = :email
+  context.attributes do |user| 
+    attribute_group(:user) do
+      attribute(:name) {user.name}
+      attribute(:email) {user.email}
+      attribute(:created_at) {user.created_at}
+    end
+  end
+end
+```
+
+Maily provides some Liquid filters that are particularly useful for time manipulation:
+
+* `plus: <number>, '<period>'`
+* `minus: <number>, '<period>'`
+
+They can be used for incrementing and decrementing the time value. `<number>` is simply an integer; `<period>` is one of 'minutes', 'hours', 'days' etc.
+
+The Mailing body can also be defined programmatically using custom Mailer. The other way is to not define explicit Mailer but rather set the subject and template as Liquid templates.
+
+```ruby
+# Using custom ActionMailer:
+config.ad_hoc_mailing :hello do |mailing|
+  mailing.list = :all_users
+  mailing.mailer_name = "UserMailer" # In this case, you should have a mailer called 'UserMailer' that defines method 'hello'.
+  mailing.enable
+end
+
+# Using Liquid templates:
+config.ad_hoc_mailing :hello do |mailing|
+  mailing.list = :all_users
+  mailing.subject = "Hello {{user.name}}!"
+  mailing.template = "What's up?"
   mailing.enable
 end
 ```
 
 ### Mailers
 
-You don't need to have any Mailer to use MailyHerald. It works perfectly fine with its generic `MailyHerald::Mailer` and mailing templates written in Luquid. 
+If you want to use your custom ActionMailers with Maily, you need to modify them a bit.
 
-But if you still want your fancy Mailer views and features, you need to modify it a bit.
+First, each Mailer you want to use with MailyHerald needs to extend the `MailyHerald::Mailer` class. 
 
-First, each Mailer you want to use with MailyHerald needs to extend `MailyHerald::Mailer` class. 
-Then each Mailer method must be named after mailing identification name and accept only one parameter which is your entity (i.e. `User` class object).
+Then each Mailer method must be named after the mailing identification name and accept only one parameter, which will be your entity (i.e. `User` class object).
 
-This setup gives you some extra instance variables available in your views:
+This setup gives you additional instance variables available to you in your views:
 
 * `@maily_entity` - entity you are sending this email to,
 * `@maily_mailing` - Mailing you are sending,
@@ -206,9 +286,9 @@ end
 
 ### Opt-outs
 
-MailyHerald allows entities to easily opt-out using direct unsubscribe urls. Each entity subscription has its own token and based on this token, opt-out URL is generated.
+MailyHerald allows entities to easily opt-out using direct unsubscribe urls. Each entity subscription has its own token and based on this token, the opt-out URL is generated.
 
-To process user opt-out requests you need to mount Maily into your app:
+To process user opt-out requests, you need to mount Maily into your app:
 
 ```ruby
 # config/routes.rb
@@ -216,50 +296,57 @@ To process user opt-out requests you need to mount Maily into your app:
 mount MailyHerald::Engine => "/unsubscribe", :as => "maily_herald_engine"
 ```
 
-Maily provides you with URL helper that generates opt-out URLs (i.e. in your ActionMailer views):
+Maily provides you with a URL helper that generates opt-out URLs (i.e. in your ActionMailer views):
 
 ```ruby
-maily_herald_engine.unsubscribe_url(@maily_subscription)
+maily_herald_engine.maily_unsubscribe_url(@maily_subscription)
 ```
 
-When you use Liquid for email templating, you should use following syntax:
+When you use Liquid for email templating, your context will always include the special attribute `subscription` that allows you to easily output unique opt-out URLs. Use the following syntax:
+
 ```
 {{subscription.token_url}}
 ```
 
-Visiting opt-out url disables subscription and by default redirects to "/".
-
-### Delivery
+Visiting an opt-out URL disables the subscription and by default redirects to "/".
 
-From now on, Maily will handle and track your regular mail deliveries:
+### Delivery and background processing
 
-```ruby
-UserMailer.hello(User.first).deliver
-```
+Scheduled MailyHerald mailings are always sent in the background. 
 
-Of course, you can also run the mailing for all users in scope at once:
+In order to make your deliveries work, you need to run MailyHerald Paperboy, which will take care of it:
 
-```ruby
-MailyHerald.dispatch(:hello).run
+```
+$ bundle exec maily_herald paperboy --start
 ```
 
-See [API Docs](http://www.rubydoc.info/gems/maily_herald) for more details about delivery methods.
+Paperboy will monitor your mailing schedules and queue their delivery. The actual sending of emails is handled in the background as a Sidekiq job, so make sure you run Sidekiq alongside Paperboy.
 
-### Background processing
+You can't manually trigger delivery of one-time, periodical and sequence mailings. Their schedules and deliveries are maintained automatically.
 
-Start MailyHerald Paperboy which will take care of your other periodical and sequence deliveries:
+Ad-hoc mailing, on the other hand, can (and should!) be manually scheduled for delivery:
 
+```ruby
+MailyHerald.ad_hoc_mailing(:password_reset).schedule_delivery_to User.first, Time.now
 ```
-$ maily_herald paperboy --start
+
+Alernatively, for Action Mailer compatibility, you can use the standard syntax for sending emails:
+
+```ruby
+UserMailer.password_reset(User.first).deliver
 ```
 
-**That's it!**
+This code will process email delivery immediately, in the current thread, just like a regular Action Mailer.
+
+### That's it!
 
 Your Maily setup is now complete.
 
+See [API Docs](http://www.rubydoc.info/gems/maily_herald) for more details about usage and configuration.
+
 ## Configuring
 
-You can configure your Maily using config file `config/maily_herald.yml`. Supported options:
+You can configure your Maily using the config file `config/maily_herald.yml`. Supported options:
 
 * `verbose`: true,false
 * `logfile`: where all the stuff is logged, usually 'log/maily_herald.log`
@@ -268,11 +355,29 @@ You can configure your Maily using config file `config/maily_herald.yml`. Suppor
 * `redis_namespace`: string
 * `redis_driver`: string
 
-## Customizing
+## Other stuff
+
+### Periodical mailing scheduling
+
+Periodical mailing is kind of a special one and has two modes of scheduling: general and individual. If you specify `start_at` as an absolute time, i.e. `"2111-01-01 11:11"`, it goes into general scheduling mode and consecutive mailings will be delivered to all subscribed entities at the same time at every period. This way you can send, for example, weekly newsletters every Monday to all subscribers.
+
+When you specify `start_at` as an individual time, i.e. `"user.start_at"`, individual scheduling mode will be enabled. In this case, delivery periods will count individually for each user and deliveries will be made accordingly.
+
+Individual scheduling mode is the only mode available for all other mailing types.
+
+### Deployments
+
+Maily has a built-in simple support for Capistrano. It supports both v2 and v3 and automates the task of starting, stopping and restarting the Paperboy daemon during deployments.
+
+To enable, just put the following line into your `Capfile`:
+
+```ruby
+require 'maily_herald/capistrano'
+```
 
 ### Opt-out URLs
 
-By default, visiting opt-out URL disables subscription and redirects to "/". You can easily customize the redirect path by specifying `token_redirect` proc:
+By default, visiting an opt-out URL silently disables the subscription and redirects to "/". You can easily customize the redirect path by specifying `token_redirect` proc:
 
 ```ruby
 # Evaluated within config:
@@ -310,7 +415,7 @@ end
 
 ### Redis namespaces
 
-If you want to use MailyHerald with non-standard Redis namespace, make sure your Sidekiq is also configured properly. This usually involves creating initializer file:
+If you want to use MailyHerald with non-standard Redis namespace, make sure your Sidekiq is also configured properly. This usually involves creating an initializer file:
 
 ```ruby
 # config/initializers/sidekiq.rb
@@ -322,7 +427,7 @@ Sidekiq.configure_client do |config|
 end
 ```
 
-Then of course you need to tell Maily about that too:
+Then make sure you tell Maily about the change:
 
 ```yaml
 # config/maily_herald.yml
@@ -330,14 +435,26 @@ Then of course you need to tell Maily about that too:
 :redis_namespace: maily
 ```
 
+## Contributing
+
+Please aim your pull requests to 'development' branch.
+
+Your changes should be well tested. To set up test environment just run:
+
+```
+RAILS_ENV=test rake db:setup
+rspec
+guard # execute specs interactively
+```
+
 ## More Information
 
-* [Home Page](http://www.mailyherald.org)
+* [Home Page](http://mailyherald.org)
 * [API Docs](http://www.rubydoc.info/gems/maily_herald)
-* Showcase (_coming soon_)
+* [Showcase](http://showcase.sology.eu/maily_herald)
 * [Sample application](https://github.com/Sology/maily_testapp)
 
-For bug reports or feature requests see the [issues on Github](https://github.com/Sology/maily_herald/issues).  
+Although we work hard on MailyHerald development, we can't guarantee it is free of bugs. If you find one, please make sure to report it using [issues tracker on Github](https://github.com/Sology/maily_herald/issues). You can also post your feature requests there too.
 
 ## License