dug 0.1.0.alpha1 → 0.1.0.alpha2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4455906bdb42a42d8fbdce98f6b73debdd0b5f1b
-  data.tar.gz: 63f162259f8dc882857627df00b17fb4ae23e28b
+  metadata.gz: 8c6c01300fe32cff493d71785c74fe0c37e02673
+  data.tar.gz: bf879e429299828cc2adf2bff39a1b30458da86c
 SHA512:
-  metadata.gz: df82930ee5ea1e54545cf0a34f62f9ddf0c53f640771e36819636c8f88e2f7cc1a755846153e8bceedaa749a92f149b87be2613342218ecc56830593b8153359
-  data.tar.gz: 0e5565de67ebf529278a01f4ec52d31cd2197a6528b22d58fed0fc7fecc5b2196a739d1783386fac853d7b552b204f55a196fae8de089302c2a1288dbdb405db
+  metadata.gz: 93dce7d68c25b9af837420525c8daad4bf489f93f1688445054f0794ea278a4b27344737b217bd26c6ce1183ca458497c72b6cd1c4effa25c854317774af7e27
+  data.tar.gz: 5aeac95bf1b2b1d41af25858c0c68e2f04874f960b6add28cb63cf67166010de76be0e578e0def24d4033e6dd546c842108cdd6d5e9fab4f09cf7f517b1e9ce0

data/.travis.yml

@@ -1,4 +1,16 @@
 language: ruby
 rvm:
+  - 2.1
+  - 2.2
   - 2.3.0
+  - jruby-head
+  - rbx
+matrix:
+  allow_failures:
+    - rvm: jruby-head
+    - rvm: rbx
+addons:
+  code_climate:
+    repo_token: 7da851c483298b23777baeb35bc0e33154313620b02d72792a9f49d4d377f44e
 before_install: gem install bundler -v 1.11.2
+script: bundle exec rake test

data/Gemfile

@@ -2,3 +2,7 @@ source 'https://rubygems.org'
 
 # Specify your gem's dependencies in dug.gemspec
 gemspec
+
+group :test do
+  gem "codeclimate-test-reporter", require: nil
+end

data/README.md

@@ -1,39 +1,179 @@
 # Dug
+[![Gem Version](https://badge.fury.io/rb/dug.svg)](https://badge.fury.io/rb/dug)
+[![Build Status](https://travis-ci.org/chrisarcand/dug.svg?branch=master)](https://travis-ci.org/chrisarcand/dug)
+[![Code Climate](https://codeclimate.com/github/chrisarcand/dug/badges/gpa.svg)](https://codeclimate.com/github/chrisarcand/dug)
+[![Test Coverage](https://codeclimate.com/github/chrisarcand/dug/badges/coverage.svg)](https://codeclimate.com/github/chrisarcand/dug/coverage)
 
-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/dug`. To experiment with that code, run `bin/console` for an interactive prompt.
+Created out of frustration. _"[D]amn yo[u], [G]mail!"_
 
-TODO: Delete this and the text above, and describe your gem
+**Dug is a simple, configurable gem to organize your GitHub notification emails in
+ways Gmail can't and in an easier-to-configure way.** It interacts with Google's
+Gmail API to do all the things that people usually do with Gmail filters (label by
+organization name, repository name) as well as parse GitHub's custom X headers to
+label your messages with things like "Mentioned by name", "Assigned to me",
+"Commented", etc.
 
-## Installation
 
-Add this line to your application's Gemfile:
+## Quick Installation
 
-```ruby
-gem 'dug'
-```
+Dug is meant to be stupid simple. It's practically a gemified script with a
+configurable API. As such, you can programmatically configure and execute Dug's
+runner class in any way you see fit (within a web app hook, a Rake task, a script,
+whatever).
 
-And then execute:
+Basic installation steps:
 
-    $ bundle
+1. Install Dug
 
-Or install it yourself as:
+  ```
+  $ gem install dug
+  ```
 
-    $ gem install dug
+2. Create a YAML Rule file. Example (`dug_rules.yml`):
 
-## Usage
+  ```
+  ---
+  organizations:
+    - rails
+    - name: rspec
+      label: RSpec
+      repositories:
+        - name: rspec-expectations
+          label: RSpec/rspec-expectations
+    - ManageIQ
 
-TODO: Write usage instructions here
+  reasons:
+    author:
+      label: Participating
+    comment:
+      label: Participating
+    mention:
+      label: Mentioned by name
+    team_mention:
+      label: Team mention
+    assign:
+      label: Assigned to me
+  ```
 
-## Development
+  The above rule file will:
+  * Label all notifications from the organization `rails` with the label `rails`, `rspec` with `RSpec`, `ManageIQ` with `ManageIQ`.
+  * Label all notifications from the repository `rspec-expectations` with the label `RSpec/rspec-expectations`
+  * Label notifications with `Participating` if I am the author of the Issue/PR or if I commented on it.
+  * Label notifications with `Mentioned by name` if I'm directly mentioned in it.
+  * Label notifications with `Team mention` if a team I am a part of is mentioned in it.
+  * Label notifications with `Assigned to me` if the Issue/PR is assigned to me.
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+3. Create all of the labels in the preceding step in Gmail, if you haven't already.
 
-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).
+4. Create a project in the [Google Developers Console](https://console.developers.google.com) to authenticate to the
+   Gmail API via OAuth 2.0. If you need help, detailed instructions are included further in this document.
 
-## Contributing
+5. Create a script. Example (`script.rb`; fill in your OAuth credentials):
+
+   ```ruby
+   require 'dug'
+
+   Dug.configure do |config|
+     # You can alternatively pass environment variables
+     # or a path to a downloadable authentication .json file from Google
+     config.client_id = "lja8w34jfo8ajer9vjsoasdufo98auow34f.apps.googleusercontent.com"
+     config.client_secret = "34t998asDF9879hjfd"
+
+     config.rule_file = File.join(Dir.pwd, "dug_rules.yml")
+   end
+
+   Dug::Runner.run
+   ```
+
+6. Run the script and watch your notifications get organized! The first time your run this you will be given a link to
+   visit in your browser to sign in to Gmail verify via a one time token.
+
+  ```
+  $ ruby script.rb
+  ```
+
+7. Set a cron and forget about it (this is what I do, 60 second polling). Or deploy Dug in a web application. Or even
+   just write a loop in your script `loop do; Dug::Runner.run; sleep 60; end`. How you run it is completely up to you,
+   and really doesn't matter.
+
+For more help, see verbose instructions below.
+
+## Verbose Installation/Usage
+
+Dug requires MRI 2.1+. Tests pass on the latest versions of JRuby and Rubinius as well.
+
+### Creating OAuth 2.0 credentials to the Gmail API
+
+[Create a project named "Dug" in the Google Developers Console and enable the Gmail
+API.](https://console.developers.google.com//start/api?id=gmail&credential=client_key)  
+Using this link guides you through the process and activates the Gmail API automatically.
+
+For more information, see [Using OAuth 2.0 to Access Google APIs](https://developers.google.com/identity/protocols/OAuth2)
+
+#### Using the created OAuth credentials
+
+There are multiple ways to use created OAuth credentials with Dug.
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/dug. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.
+* You can set the environment variables `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` for the OAuth client ID and secret, respectively.
+* In the Google Developer Console, in Credentials, there is an option to download a JSON file containing client credentials. You may set
+  the environment variable `GOOGLE_APPLICATION_CREDENTIALS` as a path to this file and it will be used.
+* You can set the client ID and secret OR credentials file path as mentioned above directly in a Dug configuration block:
+
+  ```ruby
+  Dug.configure do |config|
+    config.client_id = "lja8w34jfo8ajer9vjsoasdufo98auow34f.apps.googleusercontent.com"
+    config.client_secret = "34t998asDF9879hjfd"
+
+    # OR
+
+    config.application_credentials_file = "/path/to/file"
+  end
+  ```
+
+#### Token store
+
+Dug uses Google's file-based token store for refresh tokens from the [Google Auth
+Library for Ruby](https://github.com/google/google-auth-library-ruby). The token
+store's location can be configured using the `TOKEN_STORE_PATH` environment
+variable or within the configuration block as follows:
+
+```ruby
+Dug.configure do |config|
+  config.token_store = "/path/to/token/store"
+end
+```
+
+### More configuration options
+
+You can use public methods in Dug's configuration class to programmatically
+configure Dug without a Rules YAML file.  As a documenting example, here is the
+same scenario in the YAML file used previously in this README but within a config
+block:
+
+```ruby
+Dug.configure do |config|
+  config.set_organization_rule('rails')
+  config.set_organization_rule('rspec', label: 'RSpec')
+  config.set_organization_rule('ManageIQ')
+
+  config.set_repository_rule('rspec-expectations', label: 'RSpec/rspec-expectations')
+
+  config.set_reason_rule('author',       label: 'Participating')
+  config.set_reason_rule('comment',      label: 'Participating')
+  config.set_reason_rule('mention',      label: 'Mention by name')
+  config.set_reason_rule('team_mention', label: 'Team mention')
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`rake test` to run the tests. You can also run `bin/console` for an interactive
+prompt that will allow you to experiment.
+
+## Contributing
 
+Bug reports and pull requests are welcome on GitHub at https://github.com/chrisarcand/dug.
 
 ## License
 

data/Rakefile

@@ -7,4 +7,4 @@ Rake::TestTask.new(:test) do |t|
   t.test_files = FileList['test/**/*_test.rb']
 end
 
-task :default => :spec
+task :default => :test

data/dug.gemspec

@@ -24,5 +24,4 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "bundler", "~> 1.11"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"
-  spec.add_development_dependency "simplecov"
 end

data/lib/dug/version.rb

@@ -1,3 +1,3 @@
 module Dug
-  VERSION = "0.1.0.alpha1"
+  VERSION = "0.1.0.alpha2"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: dug
 version: !ruby/object:Gem::Version
-  version: 0.1.0.alpha1
+  version: 0.1.0.alpha2
 platform: ruby
 authors:
 - Chris Arcand
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-02-01 00:00:00.000000000 Z
+date: 2016-02-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: google-api-client
@@ -66,20 +66,6 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.0'
-- !ruby/object:Gem::Dependency
-  name: simplecov
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 description: "[D]amn yo[u], [G]mail. A gemified script to organize your GitHub notification
   emails using a simple configuration file in ways Gmail filters can't, such as X-GitHub-Reason
   headers."