teachers_pet 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 910209118ec442713281982a1e518e1444cc59a9
-  data.tar.gz: 5db06d1c2a2df29f5fa6f9ceeec71d37c7b5c5a0
+  metadata.gz: 93ce5e5b5d6591f2c8d571ca24a6fca2c8b15366
+  data.tar.gz: f32ef808412ae9c2367ba836a3830fbd5ae96d05
 SHA512:
-  metadata.gz: 7f158b180312b392af4c134264be6b7f250f950ac89012f067bf5605604eaf056702bf4d8474fe8f40efff5f1428b3937f74b947e8300af42b2e6abe71dcc8c7
-  data.tar.gz: 27c399025cd1d07af44e005fb35117b632a92a04d17428fe5c9dbbf996ed8a05b53bb7976b4ea57ec95c5c5ea1aa50ae676d5562d7ad06405307ed6f1941e5d3
+  metadata.gz: e06710f83c1fe8cb527dfe292b163b148b5ed163211624567a0a35b4238bda1f28eda81cdfacac8a2572a8241faf03f14a0226f79416e4122dff5e63b4d6a6fa
+  data.tar.gz: d58fc7219bcd4fa26d25c8428b074da3a93ea6a1a6c9ced5102e7428a4950848df90f6387917a0d51a1acfd16634c7a5401298eea9bc0355b55febb8903ba809

data/CONTRIBUTING.md

@@ -17,3 +17,10 @@ bundle exec rspec
 # or
 bundle exec guard
 ```
+
+To see test coverage information:
+
+```bash
+bundle exec rspec
+open coverage/index.html
+```

data/Guardfile

@@ -1,5 +1,7 @@
 # More info at https://github.com/guard/guard#readme
 
 guard :rspec, all_on_start: true, cmd: 'bundle exec rspec' do
-  watch(%r{^(lib|spec)/.*})
+  watch(%r{^lib/.*}) { 'spec' }
+  watch(%r{^spec/.*})
+  watch('spec/spec_helper') { 'spec' }
 end

data/README.md

@@ -1,6 +1,8 @@
 # teachers_pet [![Build Status](https://travis-ci.org/education/teachers_pet.svg?branch=master)](https://travis-ci.org/education/teachers_pet)
 
-Command line tools to help teachers use GitHub in their classrooms.
+**WARNING: This documentation may contain unreleased changes. See [rubydoc.info/gems/teachers_pet](http://rubydoc.info/gems/teachers_pet) for the version of this README corresponding to the latest release.**
+
+Command line tool to help teachers use GitHub in their classrooms.
 
 ## Philosophy
 
@@ -27,64 +29,87 @@ gem update teachers_pet
 
 To use the latest-and-greatest code from this repository, see the instructions in [CONTRIBUTING.md](CONTRIBUTING.md).
 
-## Basic Setup
+## Typical workflow
+
+...when using the [sandboxing](https://education.github.com/guide/sandboxing) method with [private repositories](https://education.github.com/guide/private_repos):
+
+### Basic setup
 
-* Create an organization (you will be an owner by default). The organization should reflect the name of your course.
-* Create a `students` file (you will be prompted for the path later)
+1. Create an organization (you will be an owner by default). The organization should reflect the name of your course. See [the classroom guide](https://education.github.com/guide#2-create-an-organization-for-your-class) for more info.
+1. Have each student/instructor create GitHub accounts.
+1. Create a `students` file (you can use an alternate filename and specify with the `--students` option if you like)
     * Individual assignments: one username per line
     * Group assignments: one team per line in the format `teamName username username username`
-* Add the GitHub username of all instructors to an 'instructors' file (one per line)
-* Run `create_teams`
+1. Add the GitHub username of all instructors to an `Owners.csv` file (one per line)
+1. Run the following:
 
-## Passwords / OAuth
+    ```bash
+    teachers_pet create_student_teams ...
+    teachers_pet add_to_team --members Owners.csv ...
+    ```
 
-The scripts will ask for your GitHub password in order to run. If you have [two factor authentication](https://help.github.com/articles/about-two-factor-authentication) enabled, [create a personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) (replace `github.com` with your host for GitHub Enterprise):
+### Assignments
+
+```bash
+teachers_pet create_repos ...
+teachers_pet push_files ...
+# Multiple times:
+teachers_pet open_issue ...
+
+# Then, after the assignment is due,
+teachers_pet clone_repos ...
+```
+
+## Authentication
+
+The scripts will ask for your GitHub password in order to run. If you have [two factor authentication](https://help.github.com/articles/about-two-factor-authentication) (2FA) enabled, [create a personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use) (replace `github.com` with your host for GitHub Enterprise):
 
 https://github.com/settings/tokens/new?description=teachers_pet&scopes=repo%2Cpublic_repo%2Cwrite%3Aorg%2Crepo%3Astatus%2Cread%3Aorg%2Cuser%2Cadmin%3Aorg
 
-Then, add the following line to your `.bash_profile`:
+Once created, specify the token using the `--token` option, or if you add the `TEACHERS_PET_GITHUB_TOKEN` environment variable to your `.bash_profile` (or equivalent – example below), it will be picked up by `teachers_pet`.
 
 ```bash
-export ghe_oauth="YOUR_TOKEN_HERE"
+# replace YOUR_TOKEN_HERE below
+echo "\n\nexport TEACHERS_PET_GITHUB_TOKEN=YOUR_TOKEN_HERE" >> ~/.bash_profile
+source ~/.bash_profile
 ```
 
 ## Actions
 
-### Creating assignments
-
-For each assignment, run `create_repos` to create a repository for each student. The repositories are technically created per team, but if you use `create_teams` first, then there will be one team per student.
-
-### Collaborator access
-
-Give collaborator access to everyone who has forked your repository.
+**To learn the options for each action, run**
 
 ```bash
-fork_collab
+teachers_pet help
+# or
+teachers_pet help COMMAND
 ```
 
-### Pushing starter files
+### Giving others access
 
-This is the workflow that we use. Create a private repository on GitHub. Clone it to your machine and place in all the necessary starter files (.gitignore and build files, like Makefile are highly recommended). Commit and push this repository to the origin.
+You may need to give other people access to various repositories using teams – the `add_to_team` command can help do this in bulk.
 
-While in the directory for the starter file repository, run the `push_repos` script.
+### Creating assignments
 
-This works by creating a git remote for each repository and thing doing a push to that repository.
+When using the [sandboxing](https://education.github.com/guide/sandboxing) setup, you will need to create the repositories for the students.  For each assignment, use the `create_repos` action to create a repository for each student.  The repositories are technically created per team, but if you use `create_student_teams` first, then there will be one team per student.
 
-### Opening issues
+### Collaborator access
+
+Give [collaborator access](https://help.github.com/articles/what-are-the-different-access-permissions#collaborator) to everyone who has forked your repository using `fork_collab`.  Mostly useful for GitHub demonstrations, where the students can quickly be added to a repository without having to worry about collecting usernames.
 
-After running `create_repos`, instructors can open issues in repos with `open_issue`.  This action requires an `issue.md` file containing the body of the issue.  The issue title and optional tags are added at runtime.
+### Pushing starter files
 
-One issue will be opened in every repo defined by the `students` file and repository name given by the user.
+When creating repositories for students, you will often want to include boilerplate files.  After running `create_repos`, create a canonical copy of the starter files (e.g. [`.gitignore`](https://github.com/github/gitignore#readme), `Makefile`s, etc.) in a repository.  From the local clone of the repository, use the `push_files` action to place that code in the repositories for each student.  This works by creating a Git remote for each student repository, and doing a `git push` to each one.
+
+### Opening issues
 
-Open issues in student repos as a way to list requirements of the assignment, goals, or instructions for patching.
+After running `create_repos`, instructors can open issues in student repos as a way to list requirements of the assignment, goals, or instructions for patching, using the `open_issue` command.
 
 ### Pulling repositories for grading
 
-When grading, use the `clone_repos` script to clone all the repositories in the organization that match the username-repository naming scheme that is generated when `create_repos` is run.
+When grading, use the `clone_repos` command to clone all the repositories in the organization that match the username-repository naming scheme that is generated when `create_repos` is run.
 
 ## Related projects
 
 * https://education.github.com/guide
 * https://github.com/hogbait/6170_repo_management
-* https://github.com/mikehelmick/edugit-scripts
 * https://github.com/UCSB-CS-Using-GitHub-In-Courses/github-acad-scripts

data/Rakefile

@@ -3,4 +3,4 @@ require 'rspec/core/rake_task'
 
 RSpec::Core::RakeTask.new(:spec)
 
-task :default => :spec
+task default: :spec

data/bin/teachers_pet

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require_relative File.join('..', 'lib', 'teachers_pet')
+TeachersPet::Cli.start(ARGV)

data/lib/teachers_pet.rb

@@ -1,4 +1,7 @@
-Dir.glob(File.join(File.dirname(__FILE__), '**', '*.rb'), &method(:require))
+require 'active_support/concern'
+
+require 'require_all'
+require_rel '.'
 
 module TeachersPet
 end

data/lib/teachers_pet/actions/add_to_team.rb

@@ -0,0 +1,31 @@
+module TeachersPet
+  module Actions
+    class AddToTeam < Base
+      def read_members_file
+        file = self.members
+        puts "Loading members to add:"
+        read_file(file).keys
+      end
+
+      def team_name
+        file = self.members
+        File.basename(file, File.extname(file))
+      end
+
+      def team
+        teams_by_name = self.client.existing_teams_by_name(self.organization)
+        teams_by_name[self.team_name] || self.client.create_team(self.organization, team_name)
+      end
+
+      def add_members_to_owners
+        member_list = self.read_members_file
+        self.client.add_users_to_team(organization, self.team, member_list)
+      end
+
+      def run
+        self.init_client
+        self.add_members_to_owners
+      end
+    end
+  end
+end

data/lib/teachers_pet/actions/base.rb

@@ -1,120 +1,53 @@
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..')
-
-require 'configuration'
+require 'active_support/core_ext/hash/keys'
 require 'octokit'
+require_relative File.join('..', 'configuration')
 
-## Common code for the edugit scripts.
 module TeachersPet
   module Actions
     class Base
-      def get_auth_method
-        auth_method = nil
-
-        choose do |menu|
-          menu.prompt = "Login via oAuth or Password? "
-          menu.choice :oAuth do
-            auth_method = 'oauth'
-          end
-          menu.choice :Password do
-            auth_method = 'password'
-          end
-        end
+      attr_reader :client, :options
 
-        auth_method
+      def initialize(opts={})
+        @options = opts.symbolize_keys
       end
 
-      def config_github
-        return unless @username.nil?
-        @api_endpoint = ask('What is the API endpoint?') { |q| q.default = Configuration.apiEndpoint }
-        @web_endpoint = ask("What is the Web endpoint?") { |q| q.default = Configuration.webEndpoint }
-
-        @username = ask('What is your username? (You must be an owner for the organization)?') { |q| q.default = ENV['USER'] }
-
-        @authmethod = self.get_auth_method
-
-        if @authmethod == 'oauth'
-            @oauthtoken = ask('What is your oAuth token?') { |q| q.default = ENV['ghe_oauth'] }
-        end
-        if @authmethod == 'password'
-            @password = ask('What is your password?') { |q| q.echo = false }
+      def method_missing(meth, *args, &block)
+        # Support boolean options ending, by calling them with '?' at the end
+        key = meth.to_s.sub(/\?\z/, '').to_sym
+        if self.options.has_key?(key)
+          self.options[key]
+        else
+          super
         end
       end
 
-      def init_client
-        self.config_github
-        puts "=" * 50
-        puts "Authenticating to GitHub..."
-        Octokit.configure do |c|
-          c.api_endpoint = @api_endpoint
-          c.web_endpoint = @web_endpoint
+      def octokit_config
+        opts = {
+          api_endpoint: self.api,
+          web_endpoint: self.web,
+          login: self.username,
           # Organizations can get big, pull in all pages
-          c.auto_paginate = true
-        end
-
-        if @authmethod == 'password'
-          @client = Octokit::Client.new(:login => @username, :password => @password)
-        end
-        if @authmethod == 'oauth'
-          @client = Octokit::Client.new(:login => @username, :access_token => @oauthtoken)
-        end
-      end
-
-      def read_organization(organization)
-        abort("GitHub client not initialized") if @client.nil?
-        @client.organization(organization)
-      end
+          auto_paginate: true
+        }
 
-      def execute(command)
-        `#{command}`
-      end
-
-      protected
-      def repository?(organization, repo_name)
-        begin
-          @client.repository("#{organization}/#{repo_name}")
-        rescue
-          return false
+        if self.options[:token]
+          opts[:access_token] = self.token
+        else
+          opts[:password] = self.password
         end
-      end
-
-      def get_students_file_path
-        ask("What is the filename of the list of students?") { |q| q.default = TeachersPet::Configuration.studentsFile }
-      end
 
-      def get_instructors_file_path
-        ask("What is the filename of the list of instructors?") { |q| q.default = TeachersPet::Configuration.instructorsFile }
+        opts
       end
 
-      def get_existing_repos_by_names(organization)
-        repos = Hash.new
-        response = @client.organization_repositories(organization)
-        print " Org repo names"
-        response.each do |repo|
-          repos[repo[:name]] = repo
-          print " '#{repo[:name]}'"
-        end
-        print "\n";
-        return repos
-      end
-
-      def get_teams_by_name(organization)
-        org_teams = @client.organization_teams(organization)
-        teams = Hash.new
-        org_teams.each do |team|
-          teams[team[:name]] = team
-        end
-        return teams
-      end
-
-      def get_team_member_logins(team_id)
-        @client.team_members(team_id).map do |member|
-          member[:login]
-        end
+      def init_client
+        puts "=" * 50
+        puts "Authenticating to GitHub..."
+        octokit = Octokit::Client.new(self.octokit_config)
+        @client = TeachersPet::ClientDecorator.new(octokit)
       end
 
-      def read_file(filename, type)
+      def read_file(filename)
         map = Hash.new
-        puts "Loading #{type}:"
         File.open(filename).each_line do |team|
           # Team can be a single user, or a team name and multiple users
           # Trim whitespace, otherwise issues occur
@@ -139,22 +72,14 @@ module TeachersPet
             end
           end
         end
-        return map
-      end
 
-      def confirm(message, abort_on_no = true)
-        # confirm
-        confirmed = false
-        choose do |menu|
-          menu.prompt = message
+        map
+      end
 
-          menu.choice :yes do confirmed = true end
-          menu.choice :no do confirmed = false end
-        end
-        if abort_on_no && !confirmed
-          abort("Creation canceled by user")
-        end
-        return confirmed
+      def read_students_file
+        student_file = self.students
+        puts "Loading students:"
+        read_file(student_file)
       end
     end
   end

data/lib/teachers_pet/actions/clone_repos.rb

@@ -1,58 +1,31 @@
-# Author: Mike Helmick
-# Clones all student repositories for a particular assignment
-#
-# Currently this will clone all student repositories into the current
-
-$LOAD_PATH << File.join(File.dirname(__FILE__), '..', '..')
-
-require 'rubygems'
-require 'highline/question'
-require 'highline/import'
-require 'highline/compatibility'
-require 'teachers_pet/actions/base'
-
 module TeachersPet
   module Actions
     class CloneRepos < Base
       def read_info
-        @repository = ask('What repository name should be cloned for each student?') { |q| q.validate = /\w+/ }
-        @organization = ask("What is the organization name?") { |q| q.default = TeachersPet::Configuration.organization }
-        @student_file = self.get_students_file_path
+        @repository = self.repository
+        @organization = self.organization
       end
 
       def load_files
-        @students = read_file(@student_file, 'Students')
+        @students = self.read_students_file
       end
 
       def get_clone_method
-        cloneMethod = 'https'
-        choose do |menu|
-          menu.prompt = "Clone via? "
-          menu.choice :ssh do
-            cloneMethod = 'ssh'
-          end
-          menu.choice :https do
-            cloneMethod = 'https'
-          end
-        end
-
-        cloneMethod
+        self.clone_method
       end
 
       def create
         cloneMethod = self.get_clone_method
 
-        confirm("Clone all repositories?")
-
         # create a repo for each student
         self.init_client
 
-        org_hash = read_organization(@organization)
+        org_hash = self.client.organization(@organization)
         abort('Organization could not be found') if org_hash.nil?
         puts "Found organization at: #{org_hash[:url]}"
 
         # Load the teams - there should be one team per student.
-        org_teams = get_teams_by_name(@organization)
+        org_teams = self.client.get_teams_by_name(@organization)
         # For each student - pull the repository if it exists
         puts "\nCloning assignment repositories for students..."
         @students.keys.each do |student|
@@ -62,16 +35,16 @@ module TeachersPet
           end
           repo_name = "#{student}-#{@repository}"
 
-          unless repository?(@organization, repo_name)
+          unless self.client.repository?(@organization, repo_name)
             puts " ** ERROR ** - Can't find expected repository '#{repo_name}'"
             next
           end
 
 
-          sshEndpoint = @web_endpoint.gsub("https://","git@").gsub("/",":")
+          sshEndpoint = self.web.gsub("https://","git@").gsub("/",":")
           command = "git clone #{sshEndpoint}#{@organization}/#{repo_name}.git"
           if cloneMethod.eql?('https')
-            command = "git clone #{@web_endpoint}#{@organization}/#{repo_name}.git"
+            command = "git clone #{self.web}#{@organization}/#{repo_name}.git"
           end
           puts " --> Cloning: '#{command}'"
           self.execute(command)