README.md in cogy-0.4.0 vs README.md in cogy-0.5.0
- old
+ new
@@ -1,27 +1,26 @@
# Cogy
[](https://travis-ci.org/skroutz/cogy)
[](https://badge.fury.io/rb/cogy)
-[](http://inch-ci.org/github/skroutz/cogy)
Cogy integrates [Cog](https://operable.io/) with Rails
in a way that writing & deploying commands from your application is a breeze.
See the API documentation [here](http://www.rubydoc.info/github/skroutz/cogy).
Refer to the [Changelog](CHANGELOG.md) to see what's changed between releases.
## Features
-- Write commands inside your Rails app, using Ruby (see [_Usage_](#usage))
-- The bundle config is generated automatically
+- Define commands from your Rails app (see [_Usage_](#usage))
+- Bundle config is generated automatically
- Commands are installed _automatically_ when you deploy (see [_Deployment_](#deployment))
-- Support for JSON responses and Templates (see [_Returning JSON to COG_](#returning-json-to-cog))
-- Customizable error templates (see [_Error template_](#error-template))
+- Supports JSON responses and Cog Templates (see [_Returning JSON to COG_](#returning-json-to-cog))
+- Customizable error template (see [_Error template_](#error-template))
-...and more on the way!
+...and [more on the way](https://github.com/skroutz/cogy/issues?q=is%3Aopen+is%3Aissue+label%3Afeature)!
## Why
Creating ChatOps commands that talk with a Rails app typically involves writing
a route, maybe a controller, an action and code to handle the command arguments
@@ -71,11 +70,11 @@
Take a look at the relevant [diagrams](diagrams/) for a detailed illustration.
## Requirements
-* [cogy bundle v0.3.0+](https://github.com/skroutz/cogy-bundle)
+* [cogy bundle v0.4.0+](https://github.com/skroutz/cogy-bundle)
* Ruby 2.1+
* Rails 4.2 (support for Rails 5 is on the way)
## Status
@@ -187,11 +186,11 @@
Info on how Cog handles JSON can be found in the [official documentation](https://cog-book.operable.io/#_returning_data_from_cog).
### Templates
-Templates are defined in their own files under `templates/` inside any of
+[Templates](https://cog-book.operable.io/#_templates) are defined in their own files under `templates/` inside any of
the [command load paths](#Configuration). For example:
```
$ tree
.
@@ -270,10 +269,14 @@
repo.log("HEAD", "cogy/", max_count: 1).first.date.strftime("%y%m%d.%H%M%S")
},
# The path in the Relay where the cogy command executable is located.
cogy_executable: "/cogcmd/cogy"
+
+ # The endpoint where Cogy is reachable at. This depends on where you've
+ # mounted the Cogy engine at.
+ cogy_endpoint: "http://www.example.com/cogy"
}
# Paths in your application where the files that define the commands live in.
# For example the default value will search for all `*.rb` files in the `cogy/`
# directory relative to the root of your application.
@@ -348,50 +351,42 @@
```
It can be overriden in the application by creating a view in
`app/views/cogy/error.text.erb`.
-## Installation Trigger
+## Testing commands
-In order to automate the process of installing the new bundle versions
-(eg. after a new command is added), you must create a [Cog Trigger](https://cog-book.operable.io/#_developing_a_trigger)
-that will perform the installation, which will be called when you deploy your
-app.
+We don't yet provide means to write tests for the commands, but you can easily
+test them by executing a request to your development server:
-The trigger will look this:
-
```shell
-$ cogctl triggers
-Name ID Enabled Pipeline
-ReleaseUrlTrigger d10df83b-a737-4fc4-8d9b-bf9627412d0a true cogy:install --url $body.url > chat://#general
+$ curl -XPOST --data "COG_ARGV_0=foo" http://localhost:3000/cogy/foo
```
-It essentially uses the [cogy bundle](https://github.com/skroutz/cogy-bundle)
-and installs the bundle config which is served by your application
-(ie. http://your-app.com/cogy/inventory).
+In the request body you may pass the complete or any part of the
+[Cog environment](https://cog-book.operable.io/#_command_environment_variables) you need.
-See [_Deployment_](#deployment) on information about how this trigger is
-invoked.
+This is essentially what the [cogy executable](https://github.com/skroutz/cogy-bundle)
+also does.
## Deployment
-Cogy provides integration with Capistrano 2 and 3.
+Cogy provides integration with Capistrano 2 & 3.
-There is the just one task, `cogy:notify_cog`, which just executes the
+There is just one task, `cogy:notify_cog`, which executes the
[installation Trigger](#installation-trigger).
The task should run
*after* the application server is restarted, so that the new commands
are picked up and served by the Inventory endpoint. In Capistrano 2 for
example, it should run after the built-in `deploy:restart` task.
The following options need to be set:
+* `Cogy.cogy_endpoint`: See [*Configuration*](#Configuration).
* `cogy_release_trigger_url`: This is the URL of the Cog Trigger that will
install the newly deployed bundle (ie. `!cogy:install`).
-* `cogy_endpoint`: Where the Cogy Engine is mounted at.
- For example `http://myapp.com/cogy`.
You can also configure the timeout value for the request to the Trigger by
setting the `cogy_trigger_timeout` option (default: 7).
The code of the task can be found [here](https://github.com/skroutz/cogy/blob/master/lib/cogy/capistrano/cogy.rake).
@@ -403,11 +398,10 @@
```ruby
# in config/deploy.rb
require "cogy/capistrano"
set :cogy_release_trigger_url, "<TRIGGER-INVOCATION-URL>"
-set :cogy_endpoint, "<COGY-MOUNT-POINT>"
after "deploy:restart", "cogy:notify_cog"
```
### Capistrano 3
@@ -422,13 +416,34 @@
```ruby
# in config/deploy.rb
set :cogy_release_trigger_url, "<TRIGGER-INVOCATION-URL>"
-set :cogy_endpoint, "<COGY-MOUNT-POINT>"
after "<app-restart-task>", "cogy:notify_cog"
```
+
+### Installation Trigger
+
+In order to automate the process of installing the new bundle versions
+(eg. after a new command is added), you must create a [Cog Trigger](https://cog-book.operable.io/#_developing_a_trigger)
+that will perform the installation, which will be called when you deploy your
+app.
+
+The trigger will look this:
+
+```shell
+$ cogctl triggers
+Name ID Enabled Pipeline
+ReleaseUrlTrigger d10df83b-a737-4fc4-8d9b-bf9627412d0a true cogy:install --url $body.url > chat://#general
+```
+
+It essentially uses the [cogy bundle](https://github.com/skroutz/cogy-bundle)
+and installs the bundle config which is served by your application
+(ie. http://your-app.com/cogy/inventory).
+
+See [_Deployment_](#deployment) on information about how this trigger is
+invoked.
## Development
Running the tests and RuboCop: