maintainers 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 9a242cfe2e2085d761f6fd899e539b342ae8ab65
-  data.tar.gz: 2b3d13830eecdd5b0e33cb6d2381ed68ba3131f8
+  metadata.gz: 637a6814e58b1d5692780afee0338f597a9e334f
+  data.tar.gz: 310211fbde7e866fc7ca8e0843705fe1449e083d
 SHA512:
-  metadata.gz: 33040a6040571e954c8e0ebc1b724cdf864a32bd5b6796f428fe46e5b7b75f9fa8559448c1881466de3f7148e1a3a0745dde4ac62ffd547dc88e8fa2c06ffe70
-  data.tar.gz: 1cb1627cd7a50e59c5c2d4d3957a12224c107ae0d5638aa931eebf62fe07d1cae3c47991922c172d0e0d54e093bb4165e171bba438532e43422c38ea43f05f3b
+  metadata.gz: 5bff305dcea9ef041947ab5c2fd7de7e2a4082498d258cc9d4ed2e12de22feca265870ad1f142948d77c009abbd628ed056e2af0ffb50de77b0009f43f380ddb
+  data.tar.gz: ff073623557c64dd1c115f43e6f25213f3b77798bdefd2726392b56d832a65d136d607bbc99d236dfcd3e9cafcc0fdb7562984c7b43ac47d514aec90ced3cc21

data/CHANGELOG

@@ -6,6 +6,14 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## [Unreleased]
 
+## [0.2.0] - 2016-09-05
+### Added
+- Add a 'validate' subcommand
+- Add a 'list' subcommand
+- Add a 'report' subcommand
+- Add half-decent usage
+- Add an optional 'file_format' field referring back to this repo
+
 ## [0.1.2] - 2016-09-02
 ### Fixed
 - Fixed (for realz) schema file reference
@@ -19,6 +27,7 @@ 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.1.2...HEAD
+[Unreleased]: https://github.com/puppetlabs/maintainers/compare/0.2.0...HEAD
+[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,5 +1,6 @@
 {
   "version": 1,
+  "file_format": "This MAINTAINERS file format is described at https://github.com/puppetlabs/maintainers",
   "issues": "https://github.com/puppetlabs/maintainers/issues",
   "people": [
     {
@@ -8,4 +9,4 @@
       "name": "Kylo Ginsberg"
     }
   ]
-}
+}

data/MAINTAINERS-example

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

data/MAINTAINERS-unmaintained_example

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

data/lib/maintainers/cli.rb

@@ -13,20 +13,57 @@ module Maintainers
     end
 
     def usage
-      puts "Imagine a usage statement here"
+      usage = <<USAGE
+usage: maintainers <command> [<args>]
+
+See below for subcommands. All operate on a file called 'MAINTAINERS'
+in the current working directory, except for 'report' which looks for
+that file throughout a github organization.
+
+create --issues <issues text> [--unmaintained]
+
+    Creates a MAINTAINERS file scaffold (but with no people yet).
+    - An 'issues' string is required - typically this is the
+      URL at which to file issues, but knock yourself out.
+    - An 'unmaintained' flag is optional - this make explicit
+      that a repo is not maintained.
+
+add --github <github id> [--email <email address] [--name <street name>]
+
+    Add a maintainer to the MAINTAINERS file. This can also be used to update
+    a maintainer (e.g. adding an 'email' or 'name'): if the specified 'github' id
+    is already in the MAINTAINERS file, the new fields will be merged with
+    the exiting ones.
+    - A 'github' id is required.
+    - An 'email' address is optional.
+    - A 'name' is optional.
+
+remove --github <github id>
+
+    Remove a maintainer from the MAINTAINERS file.
+    - A 'github' id is required.
+
+list
+
+    List the maintainers in a tabular form.
+
+validate
+
+    Validate that the MAINTAINERS file can be read. This can
+    be useful if you hand-edit the file but want to double-check
+    that it is still machine readable.
+
+report
+
+    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.
+USAGE
+      puts usage
       exit 1
     end
 
-    SUBCOMMANDS_WE_LOVE = [
-      "create",
-      "add",
-      "remove",
-      "list",
-      "report",
-      "help",
-      "--help",
-    ]
-
     # @return [Hash] Return an options hash
     def parse(args)
 
@@ -54,19 +91,18 @@ module Maintainers
          end,
         'list' => OptionParser.new do |opts|
          end,
+        'validate' => OptionParser.new do |opts|
+         end,
+        'report' => OptionParser.new do |opts|
+         end,
        }
 
-      if args.count == 0
-        $stderr.puts "Give me some args please"
-        usage
-      end
+      usage if args.count == 0
 
       subcommand = args.shift
       options[:subcommand] = subcommand
 
-      unless subcommands.keys.include? subcommand
-        usage
-      end
+      usage unless subcommands.keys.include? subcommand
 
       subcommands[subcommand].order!
 

data/lib/maintainers/runner.rb

@@ -3,6 +3,7 @@
 
 require 'json'
 require 'json-schema'
+require 'octokit'
 
 module Maintainers
   # Runner entry point
@@ -12,6 +13,9 @@ module Maintainers
 
       # for now just assume it's always MAINTAINERS
       options[:filename] ||= 'MAINTAINERS'
+
+      # for now just assume it's always puppetlabs
+      options[:org] ||= 'puppetlabs'
     end
 
     # Run, Lola, Run
@@ -24,6 +28,12 @@ module Maintainers
         add(@options)
       when 'remove'
         remove(@options)
+      when 'list'
+        list(@options)
+      when 'validate'
+        validate(@options)
+      when 'report'
+        report(@options)
       end
     end
 
@@ -35,14 +45,19 @@ module Maintainers
       JSON.parse(File.read(schema_path))
     end
 
-    def validate(maintainers)
-      JSON::Validator.validate(maintainers_schema, maintainers)
+    def validate_json(maintainers, quiet = false)
+      begin
+        JSON::Validator.validate!(maintainers_schema, maintainers)
+      rescue JSON::Schema::ValidationError => e
+        puts e unless quiet
+        false
+      end
     end
 
     def write_file(filename, maintainers)
       maintainers_json = JSON.pretty_generate(maintainers)
 
-      if !validate(maintainers_json)
+      if !validate_json(maintainers_json)
         $stderr.puts "Invalid maintainers string!"
         exit 1
       end
@@ -60,6 +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["issues"] = options[:issues]
       maintainers["people"] = []
 
@@ -106,5 +122,96 @@ module Maintainers
 
       write_file(filename, maintainers)
     end
+
+    def list(options)
+      filename = options[:filename]
+      if !File.exist?(filename)
+        $stderr.puts "No #{filename} file exists yet. You can use the 'create' subcommand to create one."
+        exit 1
+      end
+
+      maintainers_json = File.read(filename)
+      validate_json(maintainers_json)
+      maintainers = JSON.load(maintainers_json)
+
+      maintainers['people'].each { |p|
+        puts "%-16s %-20s %s" % [ p['github'], p['name'], p['email'] ]
+      }
+    end
+
+    def validate(options)
+      filename = options[:filename]
+      if !File.exist?(filename)
+        $stderr.puts "No #{filename} file exists yet. You can use the 'create' subcommand to create one."
+        exit 1
+      end
+
+      if validate_json(File.read(filename))
+        puts "#{filename} looks good"
+      else
+        puts "There's something wrong with #{filename}"
+        exit 1
+      end
+    end
+
+    def report(options)
+      puts "Ok, hang tight, this may take a while as I query github ..."
+      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"
+
+      # For now hardwire some arbitrary filters to help narrow down the
+      # number of repos reported on (and thus github API calls):
+      # - ignore repos with < 5 forks
+      # - 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 }
+
+      blocklist = [
+        'puppetlabs-modules',
+        'courseware',
+        'courseware-virtual',
+        'showoff',
+        'education-builds',
+        'robby3',
+        'pltraining-classroom',
+        'pltraining-bootstrap',
+        'sfdc_reporting',
+        'tse-control-repo',
+        'puppet-quest-guide',
+        'courseware-lvm',
+      ]
+
+      blocklisted_repos, repos = repos.partition { |repo| blocklist.include? repo.name }
+
+      no_maintainers_file_repos, repos = repos.partition { |repo|
+        begin
+          contents = client.contents("#{options[:org]}/#{repo.name}", :path => '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)
+      }
+
+      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"
+
+    end
+
   end
 end

data/lib/maintainers/version.rb

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

data/maintainers.gemspec

@@ -21,5 +21,6 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "rspec", "~> 3.0"
   spec.add_development_dependency "byebug", "~> 9.0"
 
+  spec.add_runtime_dependency     'octokit', '~> 4.3'
   spec.add_runtime_dependency     'json-schema', '~> 2.6'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: maintainers
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Puppet, Inc
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2016-09-02 00:00:00.000000000 Z
+date: 2016-09-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -66,6 +66,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '9.0'
+- !ruby/object:Gem::Dependency
+  name: octokit
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.3'
 - !ruby/object:Gem::Dependency
   name: json-schema
   requirement: !ruby/object:Gem::Requirement