Merge master

.travis.yml

@@ -6,6 +6,7 @@ rvm:
   - 2.0
   - 2.1
   - 2.2
+  - 2.3.1
 
 bundler_args: --without development
 

Gemfile

@@ -24,7 +24,7 @@ group :test do
   gem 'rspec', '~> 3.0.0'
   gem 'simplecov', :require => false
   gem 'vcr', '~> 2.9.2'
-  gem 'webmock', '>= 1.9'
+  gem 'webmock', '>= 1.9', '< 2.0.0'
 end
 
 platforms :rbx do

README.md

@@ -8,6 +8,44 @@ Ruby toolkit for the GitHub API.
 Upgrading? Check the [Upgrade Guide](#upgrading-guide) before bumping to a new
 [major version][semver].
 
+## Table of Contents
+
+1. [Philosophy](#philosophy)
+2. [Quick start](#quick-start)
+3. [Making requests](#making-requests)
+4. [Consuming resources](#consuming-resources)
+5. [Accessing HTTP responses](#accessing-http-responses)
+6. [Authentication](#authentication)
+   1. [Basic Authentication](#basic-authentication)
+   2. [OAuth access tokens](#oauth-access-tokens)
+   3. [Two-Factor Authentication](#two-factor-authentication)
+   4. [Using a .netrc file](#using-a-netrc-file)
+   5. [Application authentication](#application-authentication)
+7. [Pagination](#pagination)
+   1. [Auto pagination](#auto-pagination)
+8. [Working with GitHub Enterprise](#working-with-github-enterprise)
+   1. [Interacting with the GitHub.com APIs in GitHub Enterprise](#interacting-with-the-githubcom-apis-in-github-enterprise)
+   2. [Interacting with the GitHub Enterprise Admin APIs](#interacting-with-the-github-enterprise-admin-apis)
+   3. [Interacting with the GitHub Enterprise Management Console APIs](#interacting-with-the-github-enterprise-management-console-apis)
+9. [SSL Connection Errors](#ssl-connection-errors)
+10. [Configuration and defaults](#configuration-and-defaults)
+    1. [Configuring module defaults](#configuring-module-defaults)
+    2. [Using ENV variables](#using-env-variables)
+11. [Hypermedia agent](#hypermedia-agent)
+    1. [Hypermedia in Octokit](#hypermedia-in-octokit)
+    2. [URI templates](#uri-templates)
+    3. [The Full Hypermedia Experience™](#the-full-hypermedia-experience)
+12. [Upgrading guide](#upgrading-guide)
+    1. [Upgrading from 1.x.x](#upgrading-from-1xx)
+13. [Advanced usage](#advanced-usage)
+    1. [Debugging](#debugging)
+    2. [Caching](#caching)
+14. [Hacking on Octokit.rb](#hacking-on-octokitrb)
+    1. [Running and writing new tests](#running-and-writing-new-tests)
+15. [Supported Ruby Versions](#supported-ruby-versions)
+16. [Versioning](#versioning)
+17. [License](#license)
+
 ## Philosophy
 
 API wrappers [should reflect the idioms of the language in which they were
@@ -279,7 +317,7 @@ The GitHub Enterprise Admin APIs are under a different client: `EnterpriseAdminC
 ``` ruby
 admin_client = Octokit::EnterpriseAdminClient.new \
                           :access_token => "<your 40 char token>",
-                          :api_endpoint = "https://<hostname>/api/v3/"
+                          :api_endpoint => "https://<hostname>/api/v3/"
 
 # or
 Octokit.configure do |c|
@@ -433,7 +471,7 @@ pass `state` in the method options.
 - adds support for new [Enterprise-only APIs](#working-with-github-enterprise).
 - adds support for [Repository redirects][redirects].
 
-[list-pulls]: https://github.com/octokit/octokit.rb/commit/e48e91f736d5fce51e3bf74d7c9022aaa52f5c5c 
+[list-pulls]: https://github.com/octokit/octokit.rb/commit/e48e91f736d5fce51e3bf74d7c9022aaa52f5c5c
 [redirects]: https://developer.github.com/changes/2015-05-26-repository-redirects-are-coming/
 
 Version 3.0 includes a couple breaking changes when upgrading from v2.x.x:
@@ -528,7 +566,7 @@ Next, construct your own Faraday middleware:
 
 ```ruby
 stack = Faraday::RackBuilder.new do |builder|
-  builder.use Faraday::HttpCache
+  builder.use Faraday::HttpCache, serializer: Marshal, shared_cache: false
   builder.use Octokit::Response::RaiseError
   builder.adapter Faraday.default_adapter
 end
@@ -614,6 +652,7 @@ implementations:
 * Ruby 2.0
 * Ruby 2.1
 * Ruby 2.2
+* Ruby 2.3
 
 If something doesn't work on one of these Ruby versions, it's a bug.
 

lib/octokit/client.rb

@@ -36,12 +36,15 @@
 require 'octokit/client/pub_sub_hubbub'
 require 'octokit/client/pull_requests'
 require 'octokit/client/rate_limit'
+require 'octokit/client/reactions'
 require 'octokit/client/refs'
 require 'octokit/client/releases'
 require 'octokit/client/repositories'
+require 'octokit/client/repository_invitations'
 require 'octokit/client/say'
 require 'octokit/client/search'
 require 'octokit/client/service_status'
+require 'octokit/client/source_import'
 require 'octokit/client/stats'
 require 'octokit/client/statuses'
 require 'octokit/client/users'
@@ -84,12 +87,15 @@ class Client
     include Octokit::Client::PubSubHubbub
     include Octokit::Client::PullRequests
     include Octokit::Client::RateLimit
+    include Octokit::Client::Reactions
     include Octokit::Client::Refs
     include Octokit::Client::Releases
     include Octokit::Client::Repositories
+    include Octokit::Client::RepositoryInvitations
     include Octokit::Client::Say
     include Octokit::Client::Search
     include Octokit::Client::ServiceStatus
+    include Octokit::Client::SourceImport
     include Octokit::Client::Stats
     include Octokit::Client::Statuses
     include Octokit::Client::Users

lib/octokit/client/authorizations.rb

@@ -230,10 +230,11 @@ def authorize_url(app_id = client_id, options = {})
           raise Octokit::ApplicationCredentialsRequired.new "client_id required"
         end
         authorize_url = options.delete(:endpoint) || Octokit.web_endpoint
-        authorize_url += "login/oauth/authorize?client_id=" + app_id
+        authorize_url << "login/oauth/authorize?client_id=#{app_id}"
 
+        require 'cgi'
         options.each do |key, value|
-          authorize_url += "&" + key.to_s + "=" + value
+          authorize_url << "&#{key}=#{CGI.escape value}"
         end
 
         authorize_url

lib/octokit/client/commits.rb

@@ -126,7 +126,7 @@ def commits_on(*args)
       # @return [Array<Sawyer::Resource>] An array of hashes representing commits
       # @see https://developer.github.com/v3/repos/commits/#list-commits-on-a-repository
       # @example
-      #   Octokit.commits_on('octokit/octokit.rb', '2012-10-01', '2012-11-01')
+      #   Octokit.commits_between('octokit/octokit.rb', '2012-10-01', '2012-11-01')
       def commits_between(*args)
         arguments = Octokit::RepoArguments.new(args)
         date       = parse_date(arguments.shift)

lib/octokit/client/deployments.rb

@@ -48,6 +48,8 @@ def deployment_statuses(deployment_url, options = {})
       #
       # @param deployment_url [String] A URL for a deployment resource
       # @param state [String] The state: pending, success, failure, error
+      # @option options [String] :target_url The target URL to associate with this status. Default: ""
+      # @option options [String] :description A short description of the status. Maximum length of 140 characters. Default: ""
       # @return [Sawyer::Resource] A deployment status
       # @see https://developer.github.com/v3/repos/deployments/#create-a-deployment-status
       def create_deployment_status(deployment_url, state, options = {})

lib/octokit/client/gists.rb

@@ -75,7 +75,6 @@ def create_gist(options = {})
       #
       # @param options [Hash] Gist information.
       # @option options [String] :description
-      # @option options [Boolean] :public Sets gist visibility
       # @option options [Hash] :files Files that make up this gist. Keys
       #   should be the filename, the value a Hash with a :content key with text
       #   content of the Gist.

lib/octokit/client/issues.rb

@@ -279,6 +279,19 @@ def update_comment(repo, number, comment, options = {})
       def delete_comment(repo, number, options = {})
         boolean_from_response :delete, "#{Repository.path repo}/issues/comments/#{number}", options
       end
+
+      # Get the timeline for an issue
+      #
+      # @param repo [Integer, String, Repository, Hash] A GitHub repository
+      # @param number [Integer] Number ID of the comment
+      # @return [Sawyer::Resource] The timeline for this issue
+      # @see https://developer.github.com/v3/issues/timeline/
+      # @example Get timeline for issue #1435 on octokit/octokit.rb
+      #   Octokit.issue_timeline("octokit/octokit.rb", 1435)
+      def issue_timeline(repo, number, options = {})
+        options = ensure_api_media_type(:issue_timelines, options)
+        paginate "#{Repository.path repo}/issues/#{number}/timeline", options
+      end
     end
   end
 end

lib/octokit/client/milestones.rb

@@ -8,7 +8,7 @@ module Milestones
 
       # List milestones for a repository
       #
-      # @param repository [String, Repository, Hash] A GitHub repository.
+      # @param repository [Integer, String, Repository, Hash] A GitHub repository
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :milestone Milestone number.
       # @option options [String] :state (open) State: <tt>open</tt>, <tt>closed</tt>, or <tt>all</tt>.
@@ -19,26 +19,26 @@ module Milestones
       # @example List milestones for a repository
       #   Octokit.list_milestones("octokit/octokit.rb")
       def list_milestones(repository, options = {})
-        paginate "repos/#{Repository.new(repository)}/milestones", options
+        paginate "#{Repository.path repository}/milestones", options
       end
       alias :milestones :list_milestones
 
       # Get a single milestone for a repository
       #
-      # @param repository [String, Repository, Hash] A GitHub repository.
+      # @param repository [Integer, String, Repository, Hash] A GitHub repository
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :milestone Milestone number.
       # @return [Sawyer::Resource] A single milestone from a repository.
       # @see https://developer.github.com/v3/issues/milestones/#get-a-single-milestone
       # @example Get a single milestone for a repository
       #   Octokit.milestone("octokit/octokit.rb", 1)
       def milestone(repository, number, options = {})
-        get "repos/#{Repository.new(repository)}/milestones/#{number}", options
+        get "#{Repository.path repository}/milestones/#{number}", options
       end
 
       # Create a milestone for a repository
       #
-      # @param repository [String, Repository, Hash] A GitHub repository.
+      # @param repository [Integer, String, Repository, Hash] A GitHub repository
       # @param title [String] A unique title.
       # @param options [Hash] A customizable set of options.
       # @option options [String] :state (open) State: <tt>open</tt> or <tt>closed</tt>.
@@ -49,12 +49,12 @@ def milestone(repository, number, options = {})
       # @example Create a milestone for a repository
       #   Octokit.create_milestone("octokit/octokit.rb", "0.7.0", {:description => 'Add support for v3 of Github API'})
       def create_milestone(repository, title, options = {})
-        post "repos/#{Repository.new(repository)}/milestones", options.merge({:title => title})
+        post "#{Repository.path repository}/milestones", options.merge({:title => title})
       end
 
       # Update a milestone for a repository
       #
-      # @param repository [String, Repository, Hash] A GitHub repository.
+      # @param repository [Integer, String, Repository, Hash] A GitHub repository
       # @param number [String, Integer] ID of the milestone
       # @param options [Hash] A customizable set of options.
       # @option options [String] :title A unique title.
@@ -66,21 +66,21 @@ def create_milestone(repository, title, options = {})
       # @example Update a milestone for a repository
       #   Octokit.update_milestone("octokit/octokit.rb", 1, {:description => 'Add support for v3 of Github API'})
       def update_milestone(repository, number, options = {})
-        patch "repos/#{Repository.new(repository)}/milestones/#{number}", options
+        patch "#{Repository.path repository}/milestones/#{number}", options
       end
       alias :edit_milestone :update_milestone
 
       # Delete a single milestone for a repository
       #
-      # @param repository [String, Repository, Hash] A GitHub repository.
+      # @param repository [Integer, String, Repository, Hash] A GitHub repository
       # @param options [Hash] A customizable set of options.
       # @option options [Integer] :milestone Milestone number.
       # @return [Boolean] Success
       # @see https://developer.github.com/v3/issues/milestones/#delete-a-milestone
       # @example Delete a single milestone from a repository
       #   Octokit.delete_milestone("octokit/octokit.rb", 1)
       def delete_milestone(repository, number, options = {})
-        boolean_from_response :delete, "repos/#{Repository.new(repository)}/milestones/#{number}", options
+        boolean_from_response :delete, "#{Repository.path repository}/milestones/#{number}", options
       end
     end
   end

lib/octokit/client/organizations.rb

@@ -406,19 +406,28 @@ def team_repository?(team_id, repo, options = {})
 
       # Add team repository
       #
+      # This can also be used to update the permission of an existing team
+      #
       # Requires authenticated user to be an owner of the organization that the
       # team is associated with. Also, the repo must be owned by the
       # organization, or a direct form of a repo owned by the organization.
       #
       # @param team_id [Integer] Team id.
       # @param repo [String, Hash, Repository] A GitHub repository.
+      # @option options [String] :permission The permission to grant the team.
+      #   Only valid on organization-owned repositories.
+      #   Can be one of: <tt>pull</tt>, <tt>push</tt>, or <tt>admin</tt>.
+      #   If not specified, the team's <tt>permission</tt> attribute will be
+      #   used to determine what permission to grant the team on this repository.
       # @return [Boolean] True if successful, false otherwise.
       # @see Octokit::Repository
-      # @see https://developer.github.com/v3/orgs/teams/#add-team-repository
+      # @see https://developer.github.com/v3/orgs/teams/#add-or-update-team-repository
       # @example
       #   @client.add_team_repository(100000, 'github/developer.github.com')
       # @example
       #   @client.add_team_repo(100000, 'github/developer.github.com')
+      # @example Add a team with admin permissions
+      #   @client.add_team_repository(100000, 'github/developer.github.com', permission: 'admin')
       def add_team_repository(team_id, repo, options = {})
         boolean_from_response :put, "teams/#{team_id}/repos/#{Repository.new(repo)}", options.merge(:name => Repository.new(repo))
       end

lib/octokit/client/pull_requests.rb

@@ -222,7 +222,7 @@ def create_pull_request_comment(repo, pull_id, body, commit_id, path, position,
       # @return [Sawyer::Resource] Hash representing new comment
       # @see https://developer.github.com/v3/pulls/comments/#create-a-comment
       # @example
-      #   @client.create_pull_request_comment_reply("octokit/octokit.rb", 1903950, "done.")
+      #   @client.create_pull_request_comment_reply("octokit/octokit.rb", 163, "done.", 1903950)
       def create_pull_request_comment_reply(repo, pull_id, body, comment_id, options = {})
         options.merge!({
           :body => body,