maintainers 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 637a6814e58b1d5692780afee0338f597a9e334f
-  data.tar.gz: 310211fbde7e866fc7ca8e0843705fe1449e083d
+  metadata.gz: b180ab1f1bf4d3b38fbe24e230f23c5463880a73
+  data.tar.gz: 30df1da1ffe8477687ad3764f668885361126540
 SHA512:
-  metadata.gz: 5bff305dcea9ef041947ab5c2fd7de7e2a4082498d258cc9d4ed2e12de22feca265870ad1f142948d77c009abbd628ed056e2af0ffb50de77b0009f43f380ddb
-  data.tar.gz: ff073623557c64dd1c115f43e6f25213f3b77798bdefd2726392b56d832a65d136d607bbc99d236dfcd3e9cafcc0fdb7562984c7b43ac47d514aec90ced3cc21
+  metadata.gz: 666a0d00c79c5e08358244b53f855b0a14c3dfcba0c8d21d3e5345a7167f026426682583fb4949a460e0a26a4345e2d340f59a891dbae70737b4002117fc57d3
+  data.tar.gz: 8756b96d1523bc1c8d4b61979d998f9c981fe42a8006737892d1beba393f1060993aed83d85478a61e06c982ade7e4a5abda349a92aa47ff8d42509a34227c15

data/CHANGELOG

@@ -6,6 +6,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.1] - 2016-09-08
+### Fixed
+- Make 'report' subcommand more useful
+- Make 'file_format' value more helpful and more future-proof
+
 ## [0.2.0] - 2016-09-05
 ### Added
 - Add a 'validate' subcommand
@@ -27,7 +32,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Added
 - Initial support for a json format for MAINTAINERS
 
-[Unreleased]: https://github.com/puppetlabs/maintainers/compare/0.2.0...HEAD
+[Unreleased]: https://github.com/puppetlabs/maintainers/compare/0.2.1...HEAD
+[0.2.1]: https://github.com/puppetlabs/maintainers/compare/0.2.0...0.2.1
 [0.2.0]: https://github.com/puppetlabs/maintainers/compare/0.1.2...0.2.0
 [0.1.2]: https://github.com/puppetlabs/maintainers/compare/0.1.1...0.1.2
 [0.1.1]: https://github.com/puppetlabs/maintainers/compare/0.1.0...0.1.1

data/MAINTAINERS

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "file_format": "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers",
+  "file_format": "This MAINTAINERS file format is described at http://pup.pt/maintainers",
   "issues": "https://github.com/puppetlabs/maintainers/issues",
   "people": [
     {

data/MAINTAINERS-example

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "file_format": "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers",
+  "file_format": "This MAINTAINERS file format is described at http://pup.pt/maintainers",
   "issues": "https://github.com/graceland/issues",
   "people": [
     {

data/MAINTAINERS-unmaintained_example

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "file_format": "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers",
+  "file_format": "This MAINTAINERS file format is described at http://pup.pt/maintainers",
   "maintained": false,
   "issues": "This repo is not maintained",
   "people": []

data/README.md

@@ -24,11 +24,11 @@ At this point you might drop some comments in the resultant MAINTAINERS file.
 
 ### Add or remove a maintainer from a MAINTAINERS file
 
-Add users, optionally as a subsystem maintainer, optionally with a comment:
+Add users identified by github id, optionally specifying name, email address, and a comment.
 
 ```ruby
 maintainers add --github gracehopper --email grace@usnavy.gov --name "Grace Hopper"
-maintainers add --github gracehopper --email grace@usnavy.gov --name "Grace Hopper" --subsystem --comment "Maintains ENIAC"
+maintainers add --github gracehopper --email grace@usnavy.gov --name "Grace Hopper" --comment "Maintains ENIAC"
 ```
 
 Remove user by specifying the github id:
@@ -45,24 +45,18 @@ Emit a list of maintainers:
 maintainers list
 ```
 
-### List maintainers for a repo
-
-Emit a list of maintainers:
+### Produce a summary report of maintainers within the puppetlabs org
 
 ```ruby
-maintainers list https://github.com/gracehopper/newthing
+maintainers report
 ```
 
-### Produce a summary report of maintainers within an org
-
-```ruby
-maintainers report https://github.com/gracehopper
-```
+### Validate the MAINTAINERS file
 
-### Report all repos in an org maintained by someone
+Run this from the root of your project.
 
 ```ruby
-maintainers report --github gracehopper https://github.com/gracehopper
+maintainers validate
 ```
 
 ## Development

data/lib/maintainers/cli.rb

@@ -53,12 +53,25 @@ validate
     be useful if you hand-edit the file but want to double-check
     that it is still machine readable.
 
-report
+report [--verbose] [--details [repo|people]]
+
+    Report on maintainers throughout a github organization. By default,
+    the report just lists maintained repos, but see --details for more.
+    - The 'verbose' flag turns on some status. Note that the
+      report can take a while (a couple minutes) due to the number
+      of github API calls needed.
+    - The 'details' flag generates a report which is either
+      repo-centric, i.e. a sorted list of repos with the people
+      maintainer each, OR people-centric, i.e. a sorted list of
+      people with what repos they maintain.
 
-    Report on maintainers throughout a github organization.
     Note: for the report to include private repos, generate a github
     token with full control of private repositories, and then
     set the environment variable GITHUB_TOKEN to that token.
+    Also note that this token may not really be optional:
+    specifically, if you do *not* specify a GITHUB_TOKEN and the
+    organization has a lot of repos (hi puppetlabs), you will likely
+    hit github rate limit exceptions.
 USAGE
       puts usage
       exit 1
@@ -94,6 +107,12 @@ USAGE
         'validate' => OptionParser.new do |opts|
          end,
         'report' => OptionParser.new do |opts|
+            opts.on("-v", "--verbose", "verbosity") do |v|
+              options[:verbose] = v
+            end
+            opts.on("-d", "--details [repos|people]", "detailed report") do |v|
+              options[:details] = v
+            end
          end,
        }
 
@@ -116,6 +135,11 @@ USAGE
         usage
       end
 
+      if subcommand == 'report' && !options[:details].nil? && !['repo', 'people'].include?(options[:details])
+        $stderr.puts "--details must specify either 'repo' or 'people'"
+        usage
+      end
+
       if args.count > 0
         $stderr.puts "Unexpected additional args #{args}"
         usage

data/lib/maintainers/runner.rb

@@ -40,7 +40,7 @@ module Maintainers
     def maintainers_schema
       # I don't know what the idiomatic way is to access a non-ruby file packaged
       # with the gem. This seems gross but it works.
-      schema_path = File.join(Gem.loaded_specs['maintainers'].gem_dir, 'schema/MAINTAINERS.json')
+      schema_path = File.join(Gem.loaded_specs['maintainers'].gem_dir, 'schema/MAINTAINERS-schema.json')
 
       JSON.parse(File.read(schema_path))
     end
@@ -75,7 +75,7 @@ module Maintainers
       # minimum content for a maintainers file
       maintainers = {}
       maintainers["version"] = 1
-      maintainers["file_format"] = "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers"
+      maintainers["file_format"] = "This MAINTAINERS file format is described at http://pup.pt/maintainers"
       maintainers["issues"] = options[:issues]
       maintainers["people"] = []
 
@@ -154,13 +154,60 @@ module Maintainers
       end
     end
 
+    def report_basic(maintainers_files)
+      maintainers_files.keys.sort.each { |repo|
+        maintainers = JSON.load( maintainers_files[repo] )
+        if !maintainers['maintained'].nil? && !maintainers['maintained']
+          puts "#{repo} (unmaintained)"
+        else
+          puts "#{repo}"
+        end
+      }
+    end
+
+    def report_repo_details(maintainers_files)
+      maintainers_files.keys.sort.each { |repo|
+        puts "\t#{repo}"
+        maintainers = JSON.load( maintainers_files[repo] )
+        puts "\t\tunmaintained" if !maintainers['maintained'].nil? && !maintainers['maintained']
+        maintainers['people'].each { |person|
+          puts "\t\t#{person['name'] ? person['name'] : person['github']}"
+        }
+      }
+    end
+
+    def report_people_details(maintainers_files)
+      people = {}
+
+      # populate the people hash, building up a 'repos' array per person
+      maintainers_files.keys.sort.each { |repo|
+        maintainers = JSON.load( maintainers_files[repo] )
+        maintainers['people'].each { |person|
+          github_id = person['github']
+          if people[github_id].nil?
+            people[github_id] = person
+            people[github_id]['repos'] = [ repo ]
+          else
+            people[github_id]['repos'] <<  repo
+          end
+        }
+      }
+
+      # report out on the people hash
+      people.keys.sort.each { |github_id|
+        person = people[github_id]
+        puts "#{person['name'] ? person['name'] : person['github']} is maintaining:"
+        person['repos'].each { |repo| puts "\t#{repo}" }
+      }
+    end
+
     def report(options)
-      puts "Ok, hang tight, this may take a while as I query github ..."
+      puts "Ok, hang tight, this may take a while as I query github ..." if options[:verbose]
       client = Octokit::Client.new(:access_token => ENV['GITHUB_TOKEN'], :auto_paginate => true)
 
       repos = client.org_repos(options[:org])
 
-      puts "Found a total of #{repos.count} #{options[:org]} repos"
+      puts "Found a total of #{repos.count} #{options[:org]} repos" if options[:verbose]
 
       # For now hardwire some arbitrary filters to help narrow down the
       # number of repos reported on (and thus github API calls):
@@ -168,7 +215,7 @@ module Maintainers
       # - ignore repos on a blocklist
       # There are pretty arbitrary lines, so could be parameterized (or dropped).
 
-      lightly_forked_repos, repos = repos.partition { |repo| repo.forks < 5 }
+      lightly_forked, repos = repos.partition { |repo| repo.forks < 5 }
 
       blocklist = [
         'puppetlabs-modules',
@@ -185,31 +232,49 @@ module Maintainers
         'courseware-lvm',
       ]
 
-      blocklisted_repos, repos = repos.partition { |repo| blocklist.include? repo.name }
+      blocklisted, repos = repos.partition { |repo| blocklist.include? repo.name }
 
-      no_maintainers_file_repos, repos = repos.partition { |repo|
+      # hash of repo name to maintainers json blob
+      maintainers_files = { }
+
+      no_maintainers_file, repos = repos.partition { |repo|
         begin
           contents = client.contents("#{options[:org]}/#{repo.name}", :path => 'MAINTAINERS')
+
+          # the file content is base64 encoded with some '\n's sprinkled in.
+          # the split.join maneuver below strips out those '\n' sprinkles.
+          maintainers = Base64.decode64(contents[:content].split.join)
+          maintainers_files[repo.name] = maintainers
         rescue Octokit::NotFound
         end
 
         contents.nil?
       }
 
-      unrecognized_maintainers_file_repos, repos = repos.partition { |repo|
-        contents = client.contents("#{options[:org]}/#{repo.name}", :path => 'MAINTAINERS')
-        # the file content is base64 encoded with some '\n's sprinkled in.
-        # the split.join maneuver below strips out those '\n' sprinkles.
-        maintainers = Base64.decode64(contents[:content].split.join)
-
-        !validate_json(maintainers, true)
+      # ok, kinda awkward and not sure if this is worth reporting on?
+      # but some repos may contain a file called MAINTAINERS but in a
+      # different format
+      unrecognized_maintainers_file, repos = repos.partition { |repo|
+        !validate_json(maintainers_files[repo.name], true)
       }
+      unrecognized_maintainers_file.each { |repo| maintainers_files.delete(repo.name) }
+
+      if options[:verbose]
+        puts "Skipped #{lightly_forked.count} repos with fewer than 5 forks" if lightly_forked && lightly_forked.count > 0
+        puts "Skipped #{blocklisted.count} repos on a blocklist" if blocklisted && blocklisted.count > 0
+        puts "Skipped #{no_maintainers_file.count} without a MAINTAINERS file" if no_maintainers_file && no_maintainers_file.count > 0
+        puts "Skipped #{unrecognized_maintainers_file.count} with a MAINTAINERS file in a different format" if unrecognized_maintainers_file && unrecognized_maintainers_file.count > 0
+        puts "Found #{repos.count} repos with MAINTAINERS files"
+      end
 
-      puts "Skipped #{lightly_forked_repos.count} repos with fewer than 5 forks" if lightly_forked_repos
-      puts "Skipped #{blocklisted_repos.count} repos on a blocklist" if blocklisted_repos
-      puts "Skipped #{no_maintainers_file_repos.count} without a MAINTAINERS file" if no_maintainers_file_repos
-      puts "Skipped #{unrecognized_maintainers_file_repos.count} with a MAINTAINERS file in a different format" if unrecognized_maintainers_file_repos
-      puts "Found #{repos.count} repos with MAINTAINERS files"
+      case options[:details]
+      when 'repo'
+        report_repo_details(maintainers_files)
+      when 'people'
+        report_people_details(maintainers_files)
+      else
+        report_basic(maintainers_files)
+      end
 
     end
 

data/lib/maintainers/version.rb

@@ -1,3 +1,3 @@
 module Maintainers
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: maintainers
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Puppet, Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-05 00:00:00.000000000 Z
+date: 2016-09-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -121,7 +121,7 @@ files:
 - lib/maintainers/runner.rb
 - lib/maintainers/version.rb
 - maintainers.gemspec
-- schema/MAINTAINERS.json
+- schema/MAINTAINERS-schema.json
 - schema/json-meta-schema.json
 homepage: https://github.com/puppetlabs/maintainers
 licenses: []