Merge branch 'master' into document-status-hook

technoweenie · technoweenie · commit 4588a7edf0ab · 2013-10-03T10:24:29.000-06:00
diff --git a/content/v3/activity/events/types.md b/content/v3/activity/events/types.md
@@ -19,6 +19,8 @@ They're only created for various internal and repository hooks.
 
 ## CommitCommentEvent
 
+Triggered when a [commit comment](/v3/repos/comments/#list-commit-comments-for-a-repository) is created.
+
 Hook name: `commit_comment`
 
 comment
@@ -45,7 +47,7 @@ description
 
 ## DeleteEvent
 
-Represents a deleted branch or tag.
+Represents a [deleted branch or tag](/v3/git/refs/#delete-a-reference).
 
 Hook name: `delete`
 
@@ -57,21 +59,29 @@ ref
 
 ## DownloadEvent
 
+Triggered when a new [download](/v3/repos/downloads/) is created.
+
 Hook name: `download`
 
+Events of this type are **no longer created**, but it's possible that they exist in timelines of some users.
+
 download
 : **object** - The [download](/v3/repos/downloads/) that was just
 created.
 
 ## FollowEvent
 
+Triggered when a user [follows another user](/v3/users/followers/#follow-a-user).
+
 Hook name: `follow`
 
 target
 : **object** - The [user](/v3/users) that was just followed.
 
 ## ForkEvent
 
+Triggered when a user [forks a repository](/v3/repos/forks/#create-a-fork).
+
 Hook name: `fork`
 
 forkee
@@ -81,6 +91,8 @@ forkee
 
 Triggered when a patch is applied in the Fork Queue.
 
+Events of this type are **no longer created**, but it's possible that they exist in timelines of some users.
+
 Hook name: `fork_apply`
 
 head
@@ -94,8 +106,12 @@ after
 
 ## GistEvent
 
+Triggered when a [Gist](/v3/gists/) is created or updated.
+
 Hook name: `gist`
 
+Events of this type are **no longer created**, but it's possible that they exist in timelines of some users.
+
 action
 : **string** - The action that was performed. Can be "create" or "update"
 
@@ -104,6 +120,8 @@ gist
 
 ## GollumEvent
 
+Triggered when a Wiki page is created or updated.
+
 Hook name: `gollum`
 
 pages
@@ -116,7 +134,7 @@ pages[][title]
 : **string** - The current page title.
 
 pages[][action]
-: **string** - The action that was performed on the page.
+: **string** - The action that was performed on the page. Can be "created" or "edited".
 
 pages[][sha]
 : **string** - The latest commit SHA of the page.
@@ -126,10 +144,12 @@ pages[][html_url]
 
 ## IssueCommentEvent
 
+Triggered when an [issue comment](/v3/issues/comments/) is created.
+
 Hook name: `issue_comment`
 
 action
-: **string** - The action that was performed on the comment.
+: **string** - The action that was performed on the comment. Currently, can only be "created".
 
 issue
 : **object** - The [issue](/v3/issues/) the comment belongs to.
@@ -139,6 +159,8 @@ comment
 
 ## IssuesEvent
 
+Triggered when an [issue](/v3/issues) is created, closed or reopened.
+
 Hook name: `issues`
 
 action
@@ -150,27 +172,28 @@ issue
 
 ## MemberEvent
 
-Triggered when a user is added as a collaborator to a repository.
+Triggered when a user is [added as a collaborator](/v3/repos/collaborators/#add-collaborator) to a repository.
 
 Hook name: `member`
 
 member
 : **object** - The [user](/v3/users/) that was added.
 
 action
-: **string** - The action that was performed: "added".
+: **string** - The action that was performed. Currently, can only be "added".
 
 ## PublicEvent
 
-This is triggered when a private repo is open sourced.  Without a doubt: the
-best GitHub event.
+Triggered when a private repository is [open sourced](/v3/repos/#edit).  Without a doubt: the best GitHub event.
 
 Hook name: `public`
 
 (empty payload)
 
 ## PullRequestEvent
 
+Triggered when a [pull request](/v3/pulls) is created, closed, reopened or synchronized.
+
 Hook name: `pull_request`
 
 action
@@ -185,13 +208,17 @@ pull\_request
 
 ## PullRequestReviewCommentEvent
 
+Triggered when a [comment is created on a portion of the unified diff](/v3/pulls/comments) of a pull request.
+
 Hook name: `pull_request_review_comment`
 
 comment
 : **object** - The [comment](/v3/pulls/comments) itself.
 
 ## PushEvent
 
+Triggered when a repository branch is pushed to.
+
 Hook name: `push`
 
 head
@@ -231,6 +258,8 @@ before.
 
 ## ReleaseEvent
 
+Triggered when a [release](/v3/repos/releases/#get-a-single-release) is published.
+
 Hook name: `release`
 
 action
@@ -256,6 +285,10 @@ target_url
 
 ## TeamAddEvent
 
+Triggered when a [user is added to a team](/v3/orgs/teams/#add-team-member) or when a [repository is added to a team](/v3/orgs/teams/#add-team-repo).
+
+Note: this event is created in [users' organization timelines](/v3/activity/events/#list-events-for-an-organization).
+
 Hook name: `team_add`
 
 team
@@ -270,14 +303,13 @@ repo
 
 ## WatchEvent
 
-The WatchEvent is related to starring a repository, not watching.
-See [this API blog post](http://developer.github.com/changes/2012-9-5-watcher-api/)
-for an explanation.
+The WatchEvent is related to [starring a repository](/v3/activity/starring/#star-a-repository), not [watching](/v3/activity/watching/).
+See [this API blog post](/changes/2012-9-5-watcher-api/) for an explanation.
 
-The event’s actor is the user who starred a repository, and the event’s repo is
-the repository that was starred.
+The event’s actor is the [user](/v3/users/) who starred a repository, and the
+event’s repo is the [repository](/v3/repos/) that was starred.
 
 Hook name: `watch`
 
 action
-: **string** - The action that was performed: "started".
+: **string** - The action that was performed. Currently, can only be "started".
diff --git a/content/v3/repos/downloads.md b/content/v3/repos/downloads.md
@@ -29,96 +29,6 @@ instead.
 <%= headers 200 %>
 <%= json :download %>
 
-## Create a new download (Part 1: Create the resource)
-
-Creating a new download is a two step process. You must first create a
-new download resource.
-
-    POST /repos/:owner/:repo/downloads
-
-### Input
-
-name
-: _Required_ **string**
-
-size
-: _Required_ **number** - Size of file in bytes.
-
-description
-: _Optional_ **string**
-
-content\_type
-: _Optional_ **string**
-
-<%= json \
-  :name => "new_file.jpg",
-  :size => 114034,
-  :description => "Latest release",
-  :content_type => "text/plain"
-%>
-
-### Response
-
-<%= headers 201, :Location => "https://api.github.com/user/repo/downloads/1" %>
-<%= json :create_download %>
-
-## Create a new download (Part 2: Upload file to s3)
-
-Now that you have created the download resource, you can use the
-information in the response to upload your file to s3. This can be done
-with a `POST` to the `s3_url` you got in the create response. Here is a
-brief example using curl:
-
-    curl \
-    -F "key=downloads/octocat/Hello-World/new_file.jpg" \
-    -F "acl=public-read" \
-    -F "success_action_status=201" \
-    -F "Filename=new_file.jpg" \
-    -F "AWSAccessKeyId=1ABCDEF..." \
-    -F "Policy=ewogIC..." \
-    -F "Signature=mwnF..." \
-    -F "Content-Type=image/jpeg" \
-    -F "file=@new_file.jpg" \
-    https://github.s3.amazonaws.com/
-
-NOTES
-
-The order in which you pass these fields matters! Follow the order shown
-above exactly. All parameters shown are required and if you excluded or
-modify them your upload will fail because the values are hashed and signed
-by the policy.
-
-key
-: Value of `path` field in the response.
-
-acl
-: Value of `acl` field in the response.
-
-success_action_status
-: 201, or whatever you want to get back.
-
-Filename
-: Value of `name` field in the response.
-
-AWSAccessKeyId
-: Value of `accesskeyid` field in the response.
-
-Policy
-: Value of `policy` field in the response.
-
-Signature
-: Value of `signature` field in the response.
-
-Content-Type
-: Value of `mime_type` field in the response.
-
-file
-: Local file. Example assumes the file existing in the directory where
-you are running the curl command. Yes, the `@` matters.
-
-More information about using the REST API to interact with s3 can
-be found [here](http://docs.amazonwebservices.com/AmazonS3/latest/API/).
-
 ## Delete a download
 
     DELETE /repos/:owner/:repo/downloads/:id
diff --git a/content/v3/repos/releases.md b/content/v3/repos/releases.md
@@ -185,11 +185,24 @@ name (URI query parameter)
 
 Send the raw binary content of the asset as the request body.
 
-### Response
+### Response for successful upload
 
 <%= headers 201 %>
 <%= json :release_asset %>
 
+### Response for accepted upload
+
+The upload did not complete, but we will keep trying.
+
+<%= headers 202 %>
+<%= json :release_asset %>
+
+### Response for upstream failure
+
+This may leave an empty asset with a state of "new".  It can be safely deleted.
+
+<%= headers 502 %>
+
 ## Get a single release asset
 
     GET /repos/:owner/:repo/releases/assets/:id
