how_is 12.0.0 → 13.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: f94a1942844fecd5d67a87e5bcfa10fa8cfb9218
-  data.tar.gz: 71f9b9df67822471f710bb78ecec7e8ce7e7c219
+  metadata.gz: 7e016f1b7f3e89bf467f6ecedf72a5381ddb1efa
+  data.tar.gz: b5a681c62fac3083352a7b998d8dc37e74edd3bd
 SHA512:
-  metadata.gz: 4ed0992ecdf4d9a7f4b0351ede0961e3daa82a33d759652b20643b7238fcc515487a4b820c0e4643c95e60f9ee76e1a88566c83f5ea115e4298a24b1b9cac425
-  data.tar.gz: 1fbe9fd60239c6f478164ffc3feb2e890053a87c7fd44e7cb821da869ca976f881b5c368948c00d9c48f7b4cdd87b6396d35ef039b7ff6ed9f9c2bc51822af10
+  metadata.gz: 0a99668e69ed19eacd4e430be5571600fdf55589a5a7261120ae03d8d3af43aa95b445f7385f7f3a4be443df3f3173ec79b639ab9c798944e8a1671d67595150
+  data.tar.gz: 37c55d12b41138e5fd73aa6e8fb0070de3a8999805a096836575140d70548cc73861cbe35847681aced55c34af0c4e86c384256f89fe6fe67381a90d363e2483

data/.travis.yml

@@ -1,5 +1,3 @@
 language: ruby
-script: "bundle exec rake spec"
 rvm:
-  - 2.2
-before_install: gem install bundler -v 1.11.2
+  - 2.3.3

data/CHANGELOG.md

@@ -9,10 +9,26 @@ this project adheres to [Semantic Versioning](http://semver.org).
 
 (Nothing so far.)
 
+## [v13.0.0]
+
+This release ([snapshot](https://github.com/how-is/how_is/tree/v13.0.0))
+largely focused on an API redesign.
+
+Pull requests for this release can be [viewe on
+GitHub](https://github.com/how-is/how_is/pulls?utf8=&q=is%3Apr%20created%3A2016-12-12..2017-02-09).
+
+### Changed
+
+* API overhaul. ([#115](https://github.com/how-is/how_is/issues/115), [#117](https://github.com/how-is/how_is/pull/117))
+* Raise an exception/show a CLI warning if the provided repository name
+  isn't in the "user/repo" format.
+  ([#98](https://github.com/how-is/how_is/pull/98))
+
 ## [v12.0.0]
 
-This release largely focused on refactoring and developer experience
-improvements (e.g. adding Rake tasks and improving the generated JSON and HTML).
+This release ([snapshot](https://github.com/how-is/how_is/tree/v12.0.0))
+largely focused on refactoring and developer experience improvements
+(e.g. adding Rake tasks and improving the generated JSON and HTML).
 
 Pull Requests for this release can be [viewed on
 GitHub](https://github.com/how-is/how_is/pulls?utf8=&q=is%3Apr%20created%3A2016-11-11..2016-12-11).
@@ -35,6 +51,9 @@ GitHub](https://github.com/how-is/how_is/pulls?utf8=&q=is%3Apr%20created%3A2016-
 
 ## [11.0.0]
 
+This release ([snapshot](https://github.com/how-is/how_is/tree/v11.0.0))
+removed PDF reports, handles more edge cases, and improves tests.
+
 ### Added
 
 - Document Ruby API

data/ISSUES.md

@@ -0,0 +1,86 @@
+# Issue Management
+
+The goal of issue management is to organize the work that needs to be
+done when working on a project, by allowing users to report bugs,
+request features or documentation, and start discussions.
+
+To simplify that task, issues have _labels_. The purpose of labels is to
+group issues in ways developers find useful. The obvious examples being
+bug reports and feature requests.
+
+This document is intended as a guide to help you understand what labels
+on a given issue mean, or to help you choose labels for a new issue.
+
+Labels on this repository are grouped, using the section before the
+first colon in an issue name.
+
+Issue groups:
+
+* [(ungrouped)](#ungrouped)
+* [category](#categories)
+* [closed](#closed)
+* [size](#size)
+* [status](#status)
+* [type](#type)
+
+---
+
+## (ungrouped)
+
+### blocked
+
+An issue which can't be worked on until some other work is finished.
+If an issue has this label, it _should_ (but, unfortunately, may not)
+have an explanation of what other work needs to be done before it can be
+worked on.
+
+### duplicate
+
+A duplicate issue.
+
+### in progress
+
+An issue which is currently being worked on. This should be added when
+someone begins work on an issue.
+
+### ready
+
+An issue which is ready to be worked on. This should be removed when
+someone begins work on an issue.
+
+## categories
+
+### category: export
+
+Issues relating to exporting reports.
+
+## size
+
+### size: small
+
+An issue which should, at least in theory, be relatively simple to
+resolve.
+
+### size: large
+
+An issue which is expected to take a large amount of effort to resolve.
+
+### size: here be dragons
+
+An issue which is extremely difficult, possibly impossible, to determine
+the actual difficulty of. It could be resolved quickly, or it could grow
+significantly.
+
+## type
+
+### type: bug report
+
+A bug report.
+
+### type: feature request
+
+A request for a new feature to be added.
+
+### type: question
+
+An issue which is a question or discussion.

data/README.md

@@ -1,5 +1,5 @@
-[![Stories in Ready](https://badge.waffle.io/duckinator/how_is.png?label=ready&title=Ready)](https://waffle.io/duckinator/how_is)
-[![Build Status](https://travis-ci.org/duckinator/how_is.svg?branch=master)](https://travis-ci.org/duckinator/how_is)
+[![Stories in Ready](https://badge.waffle.io/how-is/how_is.png?label=ready&title=Ready)](https://waffle.io/how-is/how_is)
+[![Build Status](https://travis-ci.org/how-is/how_is.svg?branch=master)](https://travis-ci.org/how-is/how_is)
 
 # How is [your repo]?
 
@@ -121,7 +121,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/duckinator/how_is. 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.
+Bug reports and pull requests are welcome on GitHub at https://github.com/how-is/how_is. 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.
 
 
 ## License

data/design/01-functionality.md

@@ -0,0 +1,155 @@
+# how_is functional specification
+
+By [Ellen Marie Dash](https://twitter.com/duckinator)
+Last Updated: 2017-01-03
+
+This document is a _functional specification_ (in other words, it documents
+how the program works from an end-user perspective).
+See [02-implementation.md](02-implementation.md) for a technical
+specification (that is, how it is implemented).
+
+*This document is incomplete.* It will take significant revisions before
+this document can be considered complete.
+
+## Overview
+
+how_is is a command-line tool to quantify the state of a GitHub
+repository, and suggest actionable tasks to improve maintenance. It uses
+information from the issue tracker, the codebase itself, and third-party
+APIs to accomplish this. The expected audience is project managers, or
+people in similar roles, and software developers.
+
+## Scenarios
+
+When designing products, it helps to imagine a few real life stories of
+how actual (stereotypical) people would use them. Let's look at some
+scenarios.
+
+### Scenario 1: Jill (Project Manager)
+
+Jill is a project manager for a large software project, which is hosted
+on GitHub. She recently realized the project is falling behind on
+managing issues and pull requests, and would like to get more detailed
+information about this.
+
+She runs `how_is some_org/some_project` to generate a report, which
+contains information about the oldest and newest issues/PRs, the rate at
+which issues/PRs are being opened and closed, and what issues fall under
+whiat label. It also includes suggestions for improving management of
+the project — such as possible approaches to keep on top of new
+pull requests.
+
+### Scenario 2: Jesse (Developer)
+
+Jesse is a developer who works on the same project as Jill.
+??? Why do people use a config file? It feels like it may actually
+be redundant after the dashboard is implemented? Maybe we should discuss
+the Ruby API instead? ???
+
+## Nongoals
+
+This project is not:
+
+* A dashboard. It generates a static report. However, a dashboard is
+  going to be implemented _using_ how\_is. See:
+  [how-is/dashboard](https://github.com/how-is/dashboard).
+* Magic. It can at best give suggestions based on data. It can't know
+  the context or nuance to provide tailored advice. It needs human
+  interpretation and understanding in order to be useful.
+
+## Contents of a Report
+
+Reports will contain the following:
+
+* Number of open issues/PRs (+ links to listing of open issues/PRs).
+* Links to newest and oldest issues/PRs + dates they were opened.
+* Average issue/PR age.
+* Number of issues closed in the past month (+ link to GitHub page listing
+  them).\*
+* Number of PRs merged in the past month (+ link to GitHub page listing
+  them).\*
+* Number of issues/PRs not updated in the past month (+ link to GitHub
+  page listing them, if possible).\*
+* A graph showing the number of issues with each label (grouped by
+  category — explained later), as well as with no label (+ links
+  to lists of issues with each label).\*\*
+  * Clicking a label will pull information about issue labels from
+    various files, if they exist. Assuming one of those files exists,
+    clicking on a label will show the description of that label if it is
+    defined. If it is not defined, it will show a message explaining
+    that. The description will include a link to the file it was pulled
+    from.\*
+* Code churn (via Code Climate) — TODO: determine presentation
+  details.\*
+* Average length of time it takes for any team member to respond to a
+  new issue/PR.\*
+  * If a directory containing previous reports is specified, generate a
+    graph of this response time per week.\*
+
+Items with an asterisk (\*) have yet to be implemented.
+Items with two asterisks (\*\*) have been partially implemented.
+
+## UI Specification
+
+## Infmation about how_is
+
+`how_is --help` prints help text and exits.
+
+`how_is --version` prints the version and exits.
+
+### Generating a report
+
+How\_is can generate HTML reports for https://github.com/rubygems/rubygems.
+By default, it generates reports at `./report.html`.
+To view an HTML report, open it in aweb browser.
+
+There is no output when it succeeds.
+
+```
+$ how_is rubygems/rubygems
+$
+```
+
+### Generate a report, specifying the filename
+
+You can generate reports with other filenames, as well as different
+report formats, using the `--report FILENAME` parameter.
+
+The FILENAME can be any filename that ends with a lowercase
+extension specifying a supported format (currently `.html` and `.json`).
+
+If the filename ends with `.html` it'll generate an HTML report,
+if it ends with `.json` it'll generate a JSON report.
+
+There is no output when it succeeds.
+
+```
+$ how_is --report report.json rubygems/rubygems
+$
+```
+
+### Generate a report, using data from a JSON report
+
+If you have a JSON report (see above), you can use that to generate
+another report (probably HTML) using that data.
+
+E.g.,
+
+```
+$ how_is --from report.json --report report.html
+$
+```
+
+This generates an HTML report just like `how_is --report report.html
+REPOSITORY`, except it uses the data from `report.json` instead of
+fetching it again.
+
+tl;dr: you're using the JSON file as a cache.
+
+### Generating a report using a config file
+
+See [the README](https://github.com/how-is/how_is/blob/master/README.md#generating-reports-from-a-config-file).
+
+### Ruby API
+
+See [the README](https://github.com/how-is/how_is/blob/master/README.md#ruby-api).

data/design/02-implementation.md

@@ -0,0 +1,18 @@
+# how_is technical specification
+
+By [Ellen Marie Dash](https://twitter.com/duckinator)
+Last Updated: 2017-01-??
+
+This document is a _technical specification_ (in other words, how the
+program is implemented).
+See [01-functionality.md](01-functionality.md) for a functional
+specification (that is, how it works from an end-user perspective).
+
+*This document is incomplete.* It will take significant revisions before
+this document can be considered complete.
+
+## Overview
+
+TODO (high-level overview of architecture)
+
+## 

data/exe/how_is

@@ -19,12 +19,21 @@ opts      = result[:opts]
 options   = result[:options]
 arguments = result[:arguments]
 
-if options[:help]
-  puts result[:opts]
-elsif options[:version]
-  puts HowIs::VERSION
-elsif options[:config]
-  HowIs::CLI.new.from_config_file(options[:config])
-else
-  HowIs.generate_report_file(options)
+begin
+  if options[:help]
+    puts result[:opts]
+  elsif options[:version]
+    puts HowIs::VERSION
+  elsif options[:config]
+    HowIs.from_config_file(YAML.load_file(options[:config]))
+  else
+    HowIs.generate_report_file(options)
+  end
+rescue => e
+  if ENV['SHOW_TRACE']
+    raise
+  else
+    abort "Error: #{e.message}"
+  end
 end
+

data/how_is.gemspec

@@ -21,13 +21,8 @@ Gem::Specification.new do |spec|
   spec.add_runtime_dependency "github_api", "~> 0.14.5"
   spec.add_runtime_dependency "contracts", "~> 0.14.0"
   spec.add_runtime_dependency "slop", "~> 4.4.1"
-  spec.add_runtime_dependency "prawn", "~> 2.1.0"
 
-  spec.add_runtime_dependency "mini_magick", "~> 4.5.1"
-
-  # Travis CI only supports up to Ruby 2.2.0, but Rack 2.0+ requires Ruby 2.2.2+,
-  # so this pegs Rack to the latest version that works with Ruby 2.2.0.
-  spec.add_runtime_dependency "rack", "< 2.0"
+  spec.add_runtime_dependency "rack", "~> 2.0"
 
   spec.add_runtime_dependency "tessellator-fetcher", "~> 5.0.0"
 

data/lib/how_is/analyzer.rb

@@ -3,7 +3,7 @@ require 'ostruct'
 require 'date'
 require 'json'
 
-module HowIs
+class HowIs
   ##
   # Represents a completed analysis of the repository being analyzed.
   class Analysis < OpenStruct

data/lib/how_is/cli.rb

@@ -6,91 +6,5 @@ require 'stringio'
 class HowIs::CLI
   include Contracts::Core
 
-  DEFAULT_CONFIG_FILE = 'how_is.yml'
 
-  # Generates YAML frontmatter, as is used in Jekyll and other blog engines.
-  #
-  # E.g.,
-  #     generate_frontmatter({'foo' => "bar %{baz}"}, {'baz' => "asdf"})
-  # =>  "---\nfoo: bar asdf\n"
-  Contract C::HashOf[C::Or[String, Symbol] => String],
-           C::HashOf[C::Or[String, Symbol] => C::Any] => String
-  def generate_frontmatter(frontmatter, report_data)
-    frontmatter = convert_keys(frontmatter, :to_s)
-    report_data = convert_keys(report_data, :to_sym)
-
-    frontmatter = frontmatter.map { |k, v|
-      v = v % report_data
-
-      [k, v]
-    }.to_h
-
-    YAML.dump(frontmatter)
-  end
-
-  ##
-  # Generates a series of report files based on a YAML config file.
-  def from_config_file(config_file = nil, **kwargs)
-    config_file ||= DEFAULT_CONFIG_FILE
-
-    from_config(YAML.load_file(config_file), **kwargs)
-  end
-
-  ##
-  # Generates a series of report files based on a config Hash.
-  def from_config(config,
-        github: nil,
-        report_class: nil)
-    report_class ||= HowIs::Report
-
-    date = Date.strptime(Time.now.to_i.to_s, '%s')
-    date_string = date.strftime('%Y-%m-%d')
-    friendly_date = date.strftime('%B %d, %y')
-
-    analysis = HowIs.generate_analysis(repository: config['repository'], github: github)
-
-    report_data = {
-      repository: config['repository'],
-      date: date,
-      friendly_date: friendly_date,
-    }
-
-    config['reports'].map do |format, report_config|
-      filename = report_config['filename'] % report_data
-      file = File.join(report_config['directory'], filename)
-
-      report = report_class.export(analysis, format)
-
-      result = build_report(report_config['frontmatter'], report_data, report)
-
-      File.open(file, 'w') do |f|
-        f.puts result
-      end
-
-      result
-    end
-  end
-
-  # Combine the frontmatter, report data, and raw report into a report with
-  # frontmatter.
-  def build_report(frontmatter, report_data, report)
-    str = StringIO.new
-
-    if frontmatter
-      str.puts generate_frontmatter(frontmatter, report_data)
-      str.puts "---"
-      str.puts
-    end
-
-    str.puts report
-
-    str.string
-  end
-
-private
-  # convert_keys({'foo' => 'bar'}, :to_sym)
-  # => {:foo => 'bar'}
-  def convert_keys(data, method_name)
-    data.map {|k, v| [k.send(method_name), v]}.to_h
-  end
 end

data/lib/how_is/fetcher.rb

@@ -31,6 +31,9 @@ class HowIs::Fetcher
         github = nil)
     github ||= Github.new(auto_pagination: true)
     user, repo = repository.split('/', 2)
+    raise HowIs::CLI::OptionsError, 'To generate a report from GitHub, ' \
+                                    'provide the repository username/project. ' \
+                                    'Quitting!' unless user && repo
     issues  = github.issues.list user: user, repo: repo
     pulls   = github.pulls.list  user: user, repo: repo
 

data/lib/how_is/pulse.rb

@@ -1,6 +1,6 @@
 require 'tessellator/fetcher'
 
-module HowIs
+class HowIs
   # This entire class is a monstrous hack, because GitHub doesn't provide a good
   # API for Pulse.
   class Pulse

data/lib/how_is/report/base_report.rb

@@ -1,6 +1,6 @@
 require 'json'
 
-module HowIs
+class HowIs
   ##
   # Subclasses of BaseReport represent complete reports.
   class BaseReport < Struct.new(:analysis)

data/lib/how_is/report/html.rb

@@ -1,7 +1,7 @@
 require 'cgi'
 require 'how_is/report/base_report'
 
-module HowIs
+class HowIs
   class HtmlReport < BaseReport
     def format
       :html

data/lib/how_is/report/json.rb

@@ -1,6 +1,6 @@
 require 'how_is/report/base_report'
 
-module HowIs
+class HowIs
   class JsonReport < BaseReport
     def format
       :json

data/lib/how_is/report.rb

@@ -1,7 +1,7 @@
 require 'date'
 require 'how_is/pulse'
 
-module HowIs
+class HowIs
   class UnsupportedExportFormat < StandardError
     def initialize(format)
       super("Unsupported export format: #{format}")

data/lib/how_is/version.rb

@@ -1,3 +1,3 @@
-module HowIs
-  VERSION = "12.0.0"
+class HowIs
+  VERSION = "13.0.0"
 end

data/lib/how_is.rb

@@ -6,7 +6,7 @@ Cacert.set_in_env
 
 C = Contracts
 
-module HowIs
+class HowIs
   include Contracts::Core
 
   require 'how_is/fetcher'
@@ -25,10 +25,16 @@ module HowIs
 
   ##
   # Generates and returns a report as a String.
-  def self.generate_report(format:, **kw_args)
-    analysis = self.generate_analysis(**kw_args)
+  def initialize(repository, **kw_args)
+    @analysis = HowIs.generate_analysis(repository: repository, **kw_args)
+  end
+
+  def to_html
+    Report.export(@analysis, :html)
+  end
 
-    Report.export(analysis, format)
+  def to_json
+    Report.export(@analysis, :json)
   end
 
   ##
@@ -65,4 +71,85 @@ module HowIs
 
     analysis
   end
+
+  # Generates YAML frontmatter, as is used in Jekyll and other blog engines.
+  #
+  # E.g.,
+  #     generate_frontmatter({'foo' => "bar %{baz}"}, {'baz' => "asdf"})
+  # =>  "---\nfoo: bar asdf\n"
+  Contract C::HashOf[C::Or[String, Symbol] => String],
+           C::HashOf[C::Or[String, Symbol] => C::Any] => String
+  def self.generate_frontmatter(frontmatter, report_data)
+    frontmatter = convert_keys(frontmatter, :to_s)
+    report_data = convert_keys(report_data, :to_sym)
+
+    frontmatter = frontmatter.map { |k, v|
+      v = v % report_data
+
+      [k, v]
+    }.to_h
+
+    YAML.dump(frontmatter)
+  end
+
+  ##
+  # Generates a series of report files based on a config Hash.
+  def self.from_config(config,
+        github: nil,
+        report_class: nil)
+    report_class ||= HowIs::Report
+
+    date = Date.strptime(Time.now.to_i.to_s, '%s')
+    date_string = date.strftime('%Y-%m-%d')
+    friendly_date = date.strftime('%B %d, %y')
+
+    analysis = HowIs.generate_analysis(repository: config['repository'], github: github)
+
+    report_data = {
+      repository: config['repository'],
+      date: date,
+      friendly_date: friendly_date,
+    }
+
+    generated_reports = {}
+
+    config['reports'].map do |format, report_config|
+      filename = report_config['filename'] % report_data
+      file = File.join(report_config['directory'], filename)
+
+      report = report_class.export(analysis, format)
+
+      result = build_report(report_config['frontmatter'], report_data, report)
+
+      generated_reports[file] = result
+
+      result
+    end
+
+    generated_reports
+  end
+
+  # Combine the frontmatter, report data, and raw report into a report with
+  # frontmatter.
+  def self.build_report(frontmatter, report_data, report)
+    str = StringIO.new
+
+    if frontmatter
+      str.puts generate_frontmatter(frontmatter, report_data)
+      str.puts "---"
+      str.puts
+    end
+
+    str.puts report
+
+    str.string
+  end
+
+private
+  # convert_keys({'foo' => 'bar'}, :to_sym)
+  # => {:foo => 'bar'}
+  def self.convert_keys(data, method_name)
+    data.map {|k, v| [k.send(method_name), v]}.to_h
+  end
+
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: how_is
 version: !ruby/object:Gem::Version
-  version: 12.0.0
+  version: 13.0.0
 platform: ruby
 authors:
 - Ellen Marie Dash
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-12-11 00:00:00.000000000 Z
+date: 2017-02-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: github_api
@@ -52,46 +52,18 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 4.4.1
-- !ruby/object:Gem::Dependency
-  name: prawn
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.1.0
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 2.1.0
-- !ruby/object:Gem::Dependency
-  name: mini_magick
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 4.5.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: 4.5.1
 - !ruby/object:Gem::Dependency
   name: rack
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
         version: '2.0'
 - !ruby/object:Gem::Dependency
@@ -206,11 +178,14 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
+- ISSUES.md
 - LICENSE.txt
 - README.md
 - Rakefile
 - bin/console
 - bin/setup
+- design/01-functionality.md
+- design/02-implementation.md
 - exe/how_is
 - fixtures/vcr_cassettes/how-is-example-empty-repository.yml
 - fixtures/vcr_cassettes/how-is-example-repository.yml
@@ -248,7 +223,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.4.5.2
+rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
 summary: Quantify the health of a GitHub repository is.