Sync changes from upstream repository

Hubot · Hubot · commit ed233e91e278 · 2016-05-23T14:13:50.000-07:00
diff --git a/content/changes/2016-05-23-timeline-preview-api.md b/content/changes/2016-05-23-timeline-preview-api.md
@@ -0,0 +1,19 @@
+---
+title: Preview the Timeline API
+author_name: nickh
+---
+
+We've added an API for issue timelines, which will let you fetch a list
+of events from an issue or pull request timeline.
+
+To access [the Timeline API][docs] during the preview period, you must provide a custom [media type][media-type] in the `Accept` header:
+
+    application/vnd.github.mockingbird-preview
+
+During the preview period, we may change aspects of these API methods based on developer feedback. If we do, we will announce the changes here on the developer blog, but we will not provide any advance notice.
+
+If you have any questions or feedback, please [let us know][contact]!
+
+[media-type]: /v3/media
+[docs]: /v3/issues/timeline/
+[contact]: https://github.com/contact?form%5Bsubject%5D=Timeline+API
diff --git a/content/v3/issues/events.md b/content/v3/issues/events.md
@@ -6,7 +6,7 @@ title: Issue Events
 
 {:toc}
 
-Records various events that occur around an Issue or Pull Request. This is
+Records various events that occur around an issue or pull request. This is
 useful both for display on issue/pull request information pages and also to
 determine who should be notified of comments.
 
@@ -20,7 +20,7 @@ determine who should be notified of comments.
   <dd>The API URL for fetching the event.</dd>
 
   <dt>actor</dt>
-  <dd>Always the User object that generated the event.</dd>
+  <dd>The User object that generated the event.</dd>
 
   <dt>commit_id</dt>
   <dd>The String SHA of a commit that referenced this Issue</dd>
@@ -35,8 +35,8 @@ determine who should be notified of comments.
   <dd>The timestamp indicating when the event occurred.</dd>
 
   <dt>label</dt>
-  <dd>The Label object including 'name' and 'color' attributes. Only provided for 'labeled'
-  and 'unlabeled' events.</dd>
+  <dd>The Label object including `name` and `color` attributes. Only provided for `labeled`
+  and `unlabeled` events.</dd>
 
   <dt>assignee</dt>
   <dd>The User object which was assigned to (or unassigned from) this Issue. Only provided for 'assigned' and 'unassigned' events.</dd>
@@ -47,12 +47,12 @@ determine who should be notified of comments.
   {% endif %}
 
   <dt>milestone</dt>
-  <dd>The Milestone object including a 'title' attribute. Only provided for 'milestoned' and
-  'demilestoned' events.</dd>
+  <dd>The Milestone object including a `title` attribute. Only provided for `milestoned` and
+  `demilestoned` events.</dd>
 
   <dt>rename</dt>
-  <dd>An object containing rename details including 'from' and 'to' attributes. Only
-  provided for 'renamed' events.</dd>
+  <dd>An object containing rename details including `from` and `to` attributes. Only
+  provided for `renamed` events.</dd>
 </dl>
 
 ### Events
diff --git a/content/v3/issues/timeline.md b/content/v3/issues/timeline.md
@@ -0,0 +1,138 @@
+---
+title: Issue Timeline
+---
+
+# Timeline
+
+{:toc}
+
+Records various events that occur around an issue or pull request. This is
+useful both for display on issue and pull request information pages, as well as to
+determine who should be notified of comments.
+
+### Attributes
+
+<dl>
+  <dt>id</dt>
+  <dd>The Integer ID of the event.</dd>
+
+  <dt>url</dt>
+  <dd>The API URL for fetching the event.</dd>
+
+  <dt>actor</dt>
+  <dd>The User object that generated the event.</dd>
+
+  <dt>commit_id</dt>
+  <dd>The String SHA of a commit that referenced this Issue.</dd>
+
+  <dt>event</dt>
+  <dd>Identifies the actual type of Event that occurred.</dd>
+
+  <dt>created_at</dt>
+  <dd>The timestamp indicating when the event occurred.</dd>
+
+  <dt>label</dt>
+  <dd>The Label object including `name` and `color` attributes. Only provided for `labeled`
+  and `unlabeled` events.</dd>
+
+  <dt>assignee</dt>
+  <dd>The User object which was assigned to (or unassigned from) this Issue. Only provided for `assigned` and `unassigned` events.</dd>
+
+  <dt>assigner</dt>
+  <dd>The User object that performed the assignment (or unassignment) for this Issue. Only provided for `assigned` and `unassigned` events.</dd>
+
+  <dt>milestone</dt>
+  <dd>The Milestone object including a `title` attribute. Only provided for `milestoned` and
+  `demilestoned` events.</dd>
+
+  <dt>source</dt>
+  <dd>The `id`, `actor`, and `url` for the source of a reference from
+another issue. Only provided for `cross-referenced` events.</dd>
+
+  <dt>rename</dt>
+  <dd>An object containing rename details including `from` and `to` attributes. Only
+  provided for `renamed` events.</dd>
+</dl>
+
+### Events
+
+<dl>
+  <dt>assigned</dt>
+  <dd>The issue was assigned to the actor.</dd>
+
+  <dt>closed</dt>
+  <dd>The issue was closed by the actor. When the commit_id is present, it
+  identifies the commit that closed the issue using "closes / fixes #NN"
+  syntax.</dd>
+
+  <dt>commented</dt>
+  <dd>A comment was added to the issue.</dd>
+
+  <dt>committed</dt>
+  <dd>A commit was added to the pull request's `HEAD` branch. Only
+provided for pull requests.</dd>
+
+  <dt>cross-referenced</dt>
+  <dd>The issue was referenced from another issue. The `source`
+attribute contains the `id`, `actor`, and `url` of the reference's
+source.</dd>
+
+  <dt>demilestoned</dt>
+  <dd>The issue was removed from a milestone.</dd>
+
+  <dt>head_ref_deleted</dt>
+  <dd>The pull request's branch was deleted.</dd>
+
+  <dt>head_ref_restored</dt>
+  <dd>The pull request's branch was restored.</dd>
+
+  <dt>labeled</dt>
+  <dd>A label was added to the issue.</dd>
+
+  <dt>locked</dt>
+  <dd>The issue was locked by the actor.</dd>
+
+  <dt>mentioned</dt>
+  <dd>The actor was @mentioned in an issue body.</dd>
+
+  <dt>merged</dt>
+  <dd>The issue was merged by the actor. The `commit_id` attribute is the SHA1 of
+  the HEAD commit that was merged.</dd>
+
+  <dt>milestoned</dt>
+  <dd>The issue was added to a milestone.</dd>
+
+  <dt>referenced</dt>
+  <dd>The issue was referenced from a commit message. The `commit_id` attribute is
+  the commit SHA1 of where that happened.</dd>
+
+  <dt>renamed</dt>
+  <dd>The issue title was changed.</dd>
+
+  <dt>reopened</dt>
+  <dd>The issue was reopened by the actor.</dd>
+
+  <dt>subscribed</dt>
+  <dd>The actor subscribed to receive notifications for an issue.</dd>
+
+  <dt>unassigned</dt>
+  <dd>The actor was unassigned from the issue.</dd>
+
+  <dt>unlabeled</dt>
+  <dd>A label was removed from the issue.</dd>
+
+  <dt>unlocked</dt>
+  <dd>The issue was unlocked by the actor.</dd>
+
+  <dt>unsubscribed</dt>
+  <dd>The actor unsubscribed to stop receiving notifications for an issue.</dd>
+</dl>
+
+## List events for an issue
+
+    GET /repos/:owner/:repo/issues/:issue_number/timeline
+
+### Response
+
+<%= headers 200, :pagination => default_pagination_rels %>
+<%= json(:issue_event) { |h| [h] } %>
diff --git a/layouts/sidebar.html b/layouts/sidebar.html
@@ -47,6 +47,9 @@ <h3><a href="#" class="js-expand-btn collapsed arrow-btn" data-proofer-ignore></
           <li><a href="/v3/issues/events/">Events</a></li>
           <li><a href="/v3/issues/labels/">Labels</a></li>
           <li><a href="/v3/issues/milestones/">Milestones</a></li>
+          <% if !@item[:version].nil? && (@item[:version] == 'dotcom' || @item[:version] > 2.6) %>
+          <li><a href="/v3/issues/timeline/">Timeline</a></li>
+          <% end %>
         </ul>
       </li>
       <% if @item[:version] == 'dotcom' %>
