octokit 1.17.1 → 1.18.0

data/CHANGELOG.md

@@ -1,5 +1,6 @@
 # CHANGELOG
 
+* [1.18.0 - October 15, 2012](https://github.com/pengwynn/octokit/compare/v1.17.1...v1.18.0)
 * [1.17.1 - October 11, 2012](https://github.com/pengwynn/octokit/compare/v1.17.0...v1.17.1)
 * [1.17.0 - October 8, 2012](https://github.com/pengwynn/octokit/compare/v1.16.0...v1.17.0)
 * [1.16.0 - September 25,2012](https://github.com/pengwynn/octokit/compare/v1.15.1...v1.16.0)

data/lib/octokit/client/gists.rb

@@ -132,6 +132,74 @@ module Octokit
         response.status == 204
       end
 
+      # List gist comments
+      #
+      # @param gist_id [Integer] Gist Id.
+      # @return [Array<Hashie::Mash>] Array of hashes representing comments.
+      # @see http://developer.github.com/v3/gists/comments/#list-comments-on-a-gist
+      # @example
+      #   Octokit.gist_comments(3528645)
+      def gist_comments(gist_id, options={})
+        get "gists/#{gist_id}/comments", options, 3
+      end
+
+      # Get gist comment
+      #
+      # @param gist_comment_id [Integer] Id of the gist comment.
+      # @return [Hashie::Mash] Hash representing gist comment.
+      # @see http://developer.github.com/v3/gists/comments/#get-a-single-comment
+      # @example
+      #   Octokit.gist_comment(451398)
+      def gist_comment(gist_comment_id, options={})
+        get "gists/comments/#{gist_comment_id}", options, 3
+      end
+
+      # Create gist comment
+      #
+      # Requires authenticated client.
+      #
+      # @param gist_id [Integer] Id of the gist.
+      # @param comment [String] Comment contents.
+      # @return [Hashie::Mash] Hash representing the new comment.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/gists/comments/#create-a-comment
+      # @example
+      #   @client.create_gist_comment(3528645, 'This is very helpful.')
+      def create_gist_comment(gist_id, comment, options={})
+        options.merge!({:body => comment})
+        post "gists/#{gist_id}/comments", options, 3
+      end
+
+      # Update gist comment
+      #
+      # Requires authenticated client
+      #
+      # @param gist_comment_id [Integer] Id of the gist comment to update.
+      # @param comment [String] Updated comment contents.
+      # @return [Hashie::Mash] Hash representing the updated comment.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/gists/comments/#edit-a-comment
+      # @example
+      #   @client.update_gist_comment(3528645, ':heart:')
+      def update_gist_comment(gist_comment_id, comment, options={})
+        options.merge!({:body => comment})
+        patch "gists/comments/#{gist_comment_id}", options, 3
+      end
+
+      # Delete gist comment
+      #
+      # Requires authenticated client.
+      #
+      # @param gist_comment_id [Integer] Id of the gist comment to delete.
+      # @return [Boolean] True if comment deleted, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/gists/comments/#delete-a-comment
+      # @example
+      #   @client.delete_gist_comment(586399)
+      def delete_gist_comment(gist_comment_id, options={})
+        delete("gists/comments/#{gist_comment_id}", options, 3, true, true).status == 204
+      end
+
     end
   end
 end

data/lib/octokit/client/objects.rb

@@ -75,6 +75,60 @@ module Octokit
         }
         post("repos/#{Repository.new(repo)}/git/blobs", options.merge(parameters), 3).sha
       end
+
+      # Get a tag
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param tag_sha [String] The SHA of the tag to fetch.
+      # @return [Hashie::Mash] Hash representing the tag.
+      # @see http://developer.github.com/v3/git/tags/#get-a-tag
+      # @example Fetch a tag
+      #   Octokit.tag('pengwynn/octokit', '23aad20633f4d2981b1c7209a800db3014774e96')
+      def tag(repo, tag_sha, options={})
+        get("repos/#{Repository.new repo}/git/tags/#{tag_sha}", options, 3)
+      end
+
+      # Create a tag
+      #
+      # Requires authenticated client.
+      #
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @param tag [String] Tag string.
+      # @param message [String] Tag message.
+      # @param object_sha [String] SHA of the git object this is tagging.
+      # @param type [String] Type of the object we're tagging. Normally this is
+      #   a `commit` but it can also be a `tree` or a `blob`.
+      # @param tagger_name [String] Name of the author of the tag.
+      # @param tagger_email [String] Email of the author of the tag.
+      # @param tagger_date [string] Timestamp of when this object was tagged.
+      # @return [Hashie::Mash] Hash representing new tag.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/git/tags/#create-a-tag-object
+      # @example
+      #   @client.create_tag(
+      #     "pengwynn/octokit",
+      #     "v9000.0.0",
+      #     "Version 9000\n",
+      #     "f4cdf6eb734f32343ce3f27670c17b35f54fd82e",
+      #     "commit",
+      #     "Wynn Netherland",
+      #     "wynn.netherland@gmail.com",
+      #     "2012-06-03T17:03:11-07:00"
+      #   )
+      def create_tag(repo, tag, message, object_sha, type, tagger_name, tagger_email, tagger_date, options={})
+        options.merge!(
+          :tag => tag,
+          :message => message,
+          :object => object_sha,
+          :type => type,
+          :tagger => {
+            :name => tagger_name,
+            :email => tagger_email,
+            :date => tagger_date
+          }
+        )
+        post("repos/#{Repository.new repo}/git/tags", options, 3)
+      end
     end
   end
 end

data/lib/octokit/client/organizations.rb

@@ -1,16 +1,76 @@
 module Octokit
   class Client
     module Organizations
+      # Get an organization
+      #
+      # @param org [String] Organization GitHub username.
+      # @return [Hashie::Mash] Hash representing GitHub organization.
+      # @see http://developer.github.com/v3/orgs/#get-an-organization
+      # @example
+      #   Octokit.organization('github')
+      # @example
+      #   Octokit.org('github')
       def organization(org, options={})
         get("orgs/#{org}", options, 3)
       end
       alias :org :organization
 
+      # Update an organization.
+      #
+      # Requires authenticated client with proper organization permissions.
+      #
+      # @param org [String] Organization GitHub username.
+      # @param values [Hash] The updated organization attributes.
+      # @option values [String] :billing_email Billing email address. This address is not publicized.
+      # @option values [String] :company Company name.
+      # @option values [String] :email Publicly visible email address.
+      # @option values [String] :location Location of organization.
+      # @option values [String] :name GitHub username for organization.
+      # @return [Hashie::Mash] Hash representing GitHub organization.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/#edit-an-organization
+      # @example
+      #   @client.update_organization('github', {
+      #     :billing_email => 'support@github.com',
+      #     :company => 'GitHub',
+      #     :email => 'support@github.com',
+      #     :location => 'San Francisco',
+      #     :name => 'github'
+      #   })
+      # @example
+      #   @client.update_org('github', {:company => 'Unicorns, Inc.'})
       def update_organization(org, values, options={})
         patch("orgs/#{org}", options.merge({:organization => values}), 3)
       end
       alias :update_org :update_organization
 
+      # Get organizations for a user.
+      #
+      # Nonauthenticated calls to this method will return organizations that
+      # the user is a public member.
+      #
+      # Use an authenicated client to get both public and private organizations
+      # for a user.
+      #
+      # Calling this method on a `@client` will return that users organizations.
+      # Private organizations are included only if the `@client` is authenticated.
+      # 
+      # @param user [String] Username of the user to get list of organizations.
+      # @return [Array<Hashie::Mash>] Array of hashes representing organizations.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/#list-user-organizations
+      # @example
+      #   Octokit.organizations('pengwynn')
+      # @example
+      #   @client.organizations('pengwynn')
+      # @example
+      #   Octokit.orgs('pengwynn')
+      # @example
+      #   Octokit.list_organizations('pengwynn')
+      # @example
+      #   Octokit.list_orgs('pengwynn')
+      # @example
+      #   @client.organizations
       def organizations(user=nil, options={})
         if user
           get("users/#{user}/orgs", options, 3)
@@ -24,45 +84,171 @@ module Octokit
 
       # List organization repositories
       #
-      # @see http://developer.github.com/v3/repos/#list-organization-repositories
+      # Public repositories are available without authentication. Private repos
+      # require authenticated organization member.
+      #
       # @param org [String] Organization handle for which to list repos
+      # @option options [String] :type ('all') Filter by repository type.
+      #   `all`, `public`, `member` or `private`.
+      #
       # @return [Array<Hashie::Mash>] List of repositories
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/repos/#list-organization-repositories
+      # @example
+      #   Octokit.organization_repositories('github')
+      # @example
+      #   Octokit.org_repositories('github')
+      # @example
+      #   Octokit.org_repos('github')
+      # @example
+      #   @client.org_repos('github', {:type => 'private'})
       def organization_repositories(org, options={})
         get("orgs/#{org}/repos", options, 3)
       end
       alias :org_repositories :organization_repositories
       alias :org_repos :organization_repositories
 
+      # Get organization members
+      #
+      # Public members of the organization are returned by default. An
+      # authenticated client that is a member of the GitHub organization
+      # is required to get private members.
+      #
+      # @param org [String] Organization GitHub username.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/members/#list-members
+      # @example
+      #   Octokit.organization_members('github')
+      # @example
+      #   @client.organization_members('github')
+      # @example
+      #   Octokit.org_members('github')
       def organization_members(org, options={})
         get("orgs/#{org}/members", options, 3)
       end
       alias :org_members :organization_members
 
+      # List teams
+      #
+      # Requires authenticated organization member.
+      #
+      # @param org [String] Organization GitHub username.
+      # @return [Array<Hashie::Mash>] Array of hashes representing teams.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#list-teams
+      # @example
+      #   @client.organization_teams('github')
+      # @example
+      #   @client.org_teams('github')
       def organization_teams(org, options={})
         get("orgs/#{org}/teams", options, 3)
       end
       alias :org_teams :organization_teams
 
+      # Create team
+      #
+      # Requires authenticated organization owner. 
+      #
+      # @param org [String] Organization GitHub username.
+      # @option options [String] :name Team name.
+      # @option options [Array<String>] :repo_names Repositories for the team.
+      # @option options [String, optional] :permission ('pull') Permissions the
+      #   team has for team repositories.  
+      #
+      #   `pull` - team members can pull, but not push to or administer these repositories.    
+      #   `push` - team members can pull and push, but not administer these repositories.  
+      #   `admin` - team members can pull, push and administer these repositories. 
+      # @return [Hashie::Mash] Hash representing new team.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#create-team
+      # @example
+      #   @client.create_team('github', {
+      #     :name => 'Designers',
+      #     :repo_names => ['dotcom', 'developer.github.com'],
+      #     :permission => 'push'
+      #   })
       def create_team(org, options={})
         post("orgs/#{org}/teams", options, 3)
       end
 
+      # Get team
+      #
+      # Requires authenticated organization member.
+      #
+      # @param team_id [Integer] Team id.
+      # @return [Hashie::Mash] Hash representing team.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#get-team
+      # @example
+      #   @client.team(100000)
       def team(team_id, options={})
         get("teams/#{team_id}", options, 3)
       end
 
+      # Update team
+      #
+      # Requires authenticated organization owner.
+      #
+      # @param team_id [Integer] Team id.
+      # @option options [String] :name Team name.
+      # @option options [String] :permission Permissions the team has for team repositories.  
+      #
+      #   `pull` - team members can pull, but not push to or administer these repositories.    
+      #   `push` - team members can pull and push, but not administer these repositories.  
+      #   `admin` - team members can pull, push and administer these repositories.
+      # @return [Hashie::Mash] Hash representing updated team.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#edit-team
+      # @example
+      #   @client.update_team(100000, {
+      #     :name => 'Front-end Designers',
+      #     :permission => 'push'
+      #   })
       def update_team(team_id, options={})
         patch("teams/#{team_id}", options, 3)
       end
 
+      # Delete team
+      #
+      # Requires authenticated organization owner.
+      #
+      # @param team_id [Integer] Team id.
+      # @return [Boolean] True if deletion successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#delete-team
+      # @example
+      #   @client.delete_team(100000)
       def delete_team(team_id, options={})
         delete("teams/#{team_id}", options, 3, true, true)
       end
 
+      # List team members
+      #
+      # Requires authenticated organization member.
+      #
+      # @param team_id [Integer] Team id.
+      # @return [Array<Hashie::Mash>] Array of hashes representing users.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#list-team-members
+      # @example
+      #   @client.team_members(100000)
       def team_members(team_id, options={})
         get("teams/#{team_id}/members", options, 3)
       end
 
+      # Add team member
+      #
+      # Requires authenticated organization owner or member with team 
+      # `admin` permission.
+      #
+      # @param team_id [Integer] Team id.
+      # @param user [String] GitHub username of new team member.
+      # @return [Boolean] True on successful addition, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#add-team-member
+      # @example
+      #   @client.add_team_member(100000, 'pengwynn')
       def add_team_member(team_id, user, options={})
         # There's a bug in this API call. The docs say to leave the body blank,
         # but it fails if the body is both blank and the content-length header
@@ -70,25 +256,94 @@ module Octokit
         put("teams/#{team_id}/members/#{user}", options.merge({:name => user}), 3, true, raw=true).status == 204
       end
 
+      # Remove team member
+      #
+      # Requires authenticated organization owner or member with team 
+      # `admin` permission.
+      #
+      # @param team_id [Integer] Team id.
+      # @param user [String] GitHub username of the user to boot.
+      # @return [Boolean] True if user removed, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#remove-team-member
+      # @example
+      #   @client.remove_team_member(100000, 'pengwynn')
       def remove_team_member(team_id, user, options={})
         delete("teams/#{team_id}/members/#{user}", options, 3, true, raw=true).status == 204
       end
 
+      # List team repositories
+      #
+      # Requires authenticated organization member.
+      #
+      # @param team_id [Integer] Team id.
+      # @return [Array<Hashie::Mash>] Array of hashes representing repositories.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#list-team-repos
+      # @example
+      #   @client.team_repositories(100000)
+      # @example
+      #   @client.team_repos(100000)
       def team_repositories(team_id, options={})
         get("teams/#{team_id}/repos", options, 3)
       end
       alias :team_repos :team_repositories
 
+      # Add team repository
+      #
+      # 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.
+      # @return [Boolean] True if successful, false otherwise.
+      # @see Octokit::Client
+      # @see Octokit::Repository
+      # @see http://developer.github.com/v3/orgs/teams/#add-team-repo
+      # @example
+      #   @client.add_team_repository(100000, 'github/developer.github.com')
+      # @example
+      #   @client.add_team_repo(100000, 'github/developer.github.com')
       def add_team_repository(team_id, repo, options={})
         put("teams/#{team_id}/repos/#{Repository.new(repo)}", options.merge(:name => Repository.new(repo)), 3, true, raw=true).status == 204
       end
       alias :add_team_repo :add_team_repository
 
+      # Remove team repository
+      #
+      # Removes repository from team. Does not delete the repository.
+      #
+      # Requires authenticated organization owner.
+      #
+      # @param team_id [Integer] Team id.
+      # @param repo [String, Hash, Repository] A GitHub repository.
+      # @return [Boolean] Return true if repo removed from team, false otherwise.
+      # @see Octokit::Client
+      # @see Octokit::Repository
+      # @see http://developer.github.com/v3/orgs/teams/#remove-team-repo
+      # @example
+      #   @client.remove_team_repository(100000, 'github/developer.github.com')
+      # @example
+      #   @client.remove_team_repo(100000, 'github/developer.github.com')
       def remove_team_repository(team_id, repo, options={})
         delete("teams/#{team_id}/repos/#{Repository.new(repo)}", options, 3, true, raw=true).status == 204
       end
       alias :remove_team_repo :remove_team_repository
 
+      # Remove organization member
+      #
+      # Requires authenticated organization owner or member with team `admin` access.
+      #
+      # @param org [String] Organization GitHub username.
+      # @param user [String] GitHub username of user to remove.
+      # @return [Boolean] True if removal is successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/teams/#remove-team-member
+      # @example
+      #   @client.remove_organization_member('github', 'pengwynn')
+      # @example
+      #   @client.remove_org_member('github', 'pengwynn')
       def remove_organization_member(org, user, options={})
         # this is a synonym for: for team in org.teams: remove_team_member(team.id, user)
         # provided in the GH API v3
@@ -96,10 +351,34 @@ module Octokit
       end
       alias :remove_org_member :remove_organization_member
 
+      # Publicize a user's membership of an organization
+      #
+      # Requires authenticated organization owner.
+      #
+      # @param org [String] Organization GitHub username.
+      # @param user [String] GitHub username of user to publicize.
+      # @return [Boolean] True if publicization successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/members/#publicize-a-users-membership
+      # @example
+      #   @client.publicize_membership('github', 'pengwynn')
       def publicize_membership(org, user, options={})
         put("orgs/#{org}/public_members/#{user}", options, 3, true, raw=true).status == 204
       end
 
+      # Conceal a user's membership of an organization.
+      #
+      # Requires authenticated organization owner.
+      #
+      # @param org [String] Organization GitHub username.
+      # @param user [String] GitHub username of user to unpublicize.
+      # @return [Boolean] True of unpublicization successful, false otherwise.
+      # @see Octokit::Client
+      # @see http://developer.github.com/v3/orgs/members/#conceal-a-users-membership
+      # @example
+      #   @client.unpublicize_membership('github', 'pengwynn')
+      # @example
+      #   @client.conceal_membership('github', 'pengwynn')
       def unpublicize_membership(org, user, options={})
         delete("orgs/#{org}/public_members/#{user}", options, 3, true, raw=true).status == 204
       end