1// Copyright 2013 The go-github AUTHORS. All rights reserved.
2//
3// Use of this source code is governed by a BSD-style
4// license that can be found in the LICENSE file.
5
6package github
7
8import (
9	"bytes"
10	"context"
11	"fmt"
12	"strings"
13	"time"
14)
15
16// PullRequestsService handles communication with the pull request related
17// methods of the GitHub API.
18//
19// GitHub API docs: https://developer.github.com/v3/pulls/
20type PullRequestsService service
21
22// PullRequest represents a GitHub pull request on a repository.
23type PullRequest struct {
24	ID                  *int64     `json:"id,omitempty"`
25	Number              *int       `json:"number,omitempty"`
26	State               *string    `json:"state,omitempty"`
27	Title               *string    `json:"title,omitempty"`
28	Body                *string    `json:"body,omitempty"`
29	CreatedAt           *time.Time `json:"created_at,omitempty"`
30	UpdatedAt           *time.Time `json:"updated_at,omitempty"`
31	ClosedAt            *time.Time `json:"closed_at,omitempty"`
32	MergedAt            *time.Time `json:"merged_at,omitempty"`
33	Labels              []*Label   `json:"labels,omitempty"`
34	User                *User      `json:"user,omitempty"`
35	Merged              *bool      `json:"merged,omitempty"`
36	Mergeable           *bool      `json:"mergeable,omitempty"`
37	MergeableState      *string    `json:"mergeable_state,omitempty"`
38	MergedBy            *User      `json:"merged_by,omitempty"`
39	MergeCommitSHA      *string    `json:"merge_commit_sha,omitempty"`
40	Comments            *int       `json:"comments,omitempty"`
41	Commits             *int       `json:"commits,omitempty"`
42	Additions           *int       `json:"additions,omitempty"`
43	Deletions           *int       `json:"deletions,omitempty"`
44	ChangedFiles        *int       `json:"changed_files,omitempty"`
45	URL                 *string    `json:"url,omitempty"`
46	HTMLURL             *string    `json:"html_url,omitempty"`
47	IssueURL            *string    `json:"issue_url,omitempty"`
48	StatusesURL         *string    `json:"statuses_url,omitempty"`
49	DiffURL             *string    `json:"diff_url,omitempty"`
50	PatchURL            *string    `json:"patch_url,omitempty"`
51	CommitsURL          *string    `json:"commits_url,omitempty"`
52	CommentsURL         *string    `json:"comments_url,omitempty"`
53	ReviewCommentsURL   *string    `json:"review_comments_url,omitempty"`
54	ReviewCommentURL    *string    `json:"review_comment_url,omitempty"`
55	Assignee            *User      `json:"assignee,omitempty"`
56	Assignees           []*User    `json:"assignees,omitempty"`
57	Milestone           *Milestone `json:"milestone,omitempty"`
58	MaintainerCanModify *bool      `json:"maintainer_can_modify,omitempty"`
59	AuthorAssociation   *string    `json:"author_association,omitempty"`
60	NodeID              *string    `json:"node_id,omitempty"`
61	RequestedReviewers  []*User    `json:"requested_reviewers,omitempty"`
62
63	Head *PullRequestBranch `json:"head,omitempty"`
64	Base *PullRequestBranch `json:"base,omitempty"`
65
66	// ActiveLockReason is populated only when LockReason is provided while locking the pull request.
67	// Possible values are: "off-topic", "too heated", "resolved", and "spam".
68	ActiveLockReason *string `json:"active_lock_reason,omitempty"`
69}
70
71func (p PullRequest) String() string {
72	return Stringify(p)
73}
74
75// PullRequestBranch represents a base or head branch in a GitHub pull request.
76type PullRequestBranch struct {
77	Label *string     `json:"label,omitempty"`
78	Ref   *string     `json:"ref,omitempty"`
79	SHA   *string     `json:"sha,omitempty"`
80	Repo  *Repository `json:"repo,omitempty"`
81	User  *User       `json:"user,omitempty"`
82}
83
84// PullRequestListOptions specifies the optional parameters to the
85// PullRequestsService.List method.
86type PullRequestListOptions struct {
87	// State filters pull requests based on their state. Possible values are:
88	// open, closed. Default is "open".
89	State string `url:"state,omitempty"`
90
91	// Head filters pull requests by head user and branch name in the format of:
92	// "user:ref-name".
93	Head string `url:"head,omitempty"`
94
95	// Base filters pull requests by base branch name.
96	Base string `url:"base,omitempty"`
97
98	// Sort specifies how to sort pull requests. Possible values are: created,
99	// updated, popularity, long-running. Default is "created".
100	Sort string `url:"sort,omitempty"`
101
102	// Direction in which to sort pull requests. Possible values are: asc, desc.
103	// If Sort is "created" or not specified, Default is "desc", otherwise Default
104	// is "asc"
105	Direction string `url:"direction,omitempty"`
106
107	ListOptions
108}
109
110// List the pull requests for the specified repository.
111//
112// GitHub API docs: https://developer.github.com/v3/pulls/#list-pull-requests
113func (s *PullRequestsService) List(ctx context.Context, owner string, repo string, opt *PullRequestListOptions) ([]*PullRequest, *Response, error) {
114	u := fmt.Sprintf("repos/%v/%v/pulls", owner, repo)
115	u, err := addOptions(u, opt)
116	if err != nil {
117		return nil, nil, err
118	}
119
120	req, err := s.client.NewRequest("GET", u, nil)
121	if err != nil {
122		return nil, nil, err
123	}
124
125	// TODO: remove custom Accept header when this API fully launches.
126	acceptHeaders := []string{mediaTypeLabelDescriptionSearchPreview, mediaTypeLockReasonPreview}
127	req.Header.Set("Accept", strings.Join(acceptHeaders, ", "))
128
129	var pulls []*PullRequest
130	resp, err := s.client.Do(ctx, req, &pulls)
131	if err != nil {
132		return nil, resp, err
133	}
134
135	return pulls, resp, nil
136}
137
138// Get a single pull request.
139//
140// GitHub API docs: https://developer.github.com/v3/pulls/#get-a-single-pull-request
141func (s *PullRequestsService) Get(ctx context.Context, owner string, repo string, number int) (*PullRequest, *Response, error) {
142	u := fmt.Sprintf("repos/%v/%v/pulls/%d", owner, repo, number)
143	req, err := s.client.NewRequest("GET", u, nil)
144	if err != nil {
145		return nil, nil, err
146	}
147
148	// TODO: remove custom Accept header when this API fully launches.
149	acceptHeaders := []string{mediaTypeLabelDescriptionSearchPreview, mediaTypeLockReasonPreview}
150	req.Header.Set("Accept", strings.Join(acceptHeaders, ", "))
151
152	pull := new(PullRequest)
153	resp, err := s.client.Do(ctx, req, pull)
154	if err != nil {
155		return nil, resp, err
156	}
157
158	return pull, resp, nil
159}
160
161// GetRaw gets a single pull request in raw (diff or patch) format.
162func (s *PullRequestsService) GetRaw(ctx context.Context, owner string, repo string, number int, opt RawOptions) (string, *Response, error) {
163	u := fmt.Sprintf("repos/%v/%v/pulls/%d", owner, repo, number)
164	req, err := s.client.NewRequest("GET", u, nil)
165	if err != nil {
166		return "", nil, err
167	}
168
169	switch opt.Type {
170	case Diff:
171		req.Header.Set("Accept", mediaTypeV3Diff)
172	case Patch:
173		req.Header.Set("Accept", mediaTypeV3Patch)
174	default:
175		return "", nil, fmt.Errorf("unsupported raw type %d", opt.Type)
176	}
177
178	var buf bytes.Buffer
179	resp, err := s.client.Do(ctx, req, &buf)
180	if err != nil {
181		return "", resp, err
182	}
183
184	return buf.String(), resp, nil
185}
186
187// NewPullRequest represents a new pull request to be created.
188type NewPullRequest struct {
189	Title               *string `json:"title,omitempty"`
190	Head                *string `json:"head,omitempty"`
191	Base                *string `json:"base,omitempty"`
192	Body                *string `json:"body,omitempty"`
193	Issue               *int    `json:"issue,omitempty"`
194	MaintainerCanModify *bool   `json:"maintainer_can_modify,omitempty"`
195}
196
197// Create a new pull request on the specified repository.
198//
199// GitHub API docs: https://developer.github.com/v3/pulls/#create-a-pull-request
200func (s *PullRequestsService) Create(ctx context.Context, owner string, repo string, pull *NewPullRequest) (*PullRequest, *Response, error) {
201	u := fmt.Sprintf("repos/%v/%v/pulls", owner, repo)
202	req, err := s.client.NewRequest("POST", u, pull)
203	if err != nil {
204		return nil, nil, err
205	}
206
207	// TODO: remove custom Accept header when this API fully launches.
208	req.Header.Set("Accept", mediaTypeLabelDescriptionSearchPreview)
209
210	p := new(PullRequest)
211	resp, err := s.client.Do(ctx, req, p)
212	if err != nil {
213		return nil, resp, err
214	}
215
216	return p, resp, nil
217}
218
219type pullRequestUpdate struct {
220	Title               *string `json:"title,omitempty"`
221	Body                *string `json:"body,omitempty"`
222	State               *string `json:"state,omitempty"`
223	Base                *string `json:"base,omitempty"`
224	MaintainerCanModify *bool   `json:"maintainer_can_modify,omitempty"`
225}
226
227// Edit a pull request.
228// pull must not be nil.
229//
230// The following fields are editable: Title, Body, State, Base.Ref and MaintainerCanModify.
231// Base.Ref updates the base branch of the pull request.
232//
233// GitHub API docs: https://developer.github.com/v3/pulls/#update-a-pull-request
234func (s *PullRequestsService) Edit(ctx context.Context, owner string, repo string, number int, pull *PullRequest) (*PullRequest, *Response, error) {
235	if pull == nil {
236		return nil, nil, fmt.Errorf("pull must be provided")
237	}
238
239	u := fmt.Sprintf("repos/%v/%v/pulls/%d", owner, repo, number)
240
241	update := &pullRequestUpdate{
242		Title:               pull.Title,
243		Body:                pull.Body,
244		State:               pull.State,
245		MaintainerCanModify: pull.MaintainerCanModify,
246	}
247	if pull.Base != nil {
248		update.Base = pull.Base.Ref
249	}
250
251	req, err := s.client.NewRequest("PATCH", u, update)
252	if err != nil {
253		return nil, nil, err
254	}
255
256	// TODO: remove custom Accept header when this API fully launches.
257	acceptHeaders := []string{mediaTypeLabelDescriptionSearchPreview, mediaTypeLockReasonPreview}
258	req.Header.Set("Accept", strings.Join(acceptHeaders, ", "))
259
260	p := new(PullRequest)
261	resp, err := s.client.Do(ctx, req, p)
262	if err != nil {
263		return nil, resp, err
264	}
265
266	return p, resp, nil
267}
268
269// ListCommits lists the commits in a pull request.
270//
271// GitHub API docs: https://developer.github.com/v3/pulls/#list-commits-on-a-pull-request
272func (s *PullRequestsService) ListCommits(ctx context.Context, owner string, repo string, number int, opt *ListOptions) ([]*RepositoryCommit, *Response, error) {
273	u := fmt.Sprintf("repos/%v/%v/pulls/%d/commits", owner, repo, number)
274	u, err := addOptions(u, opt)
275	if err != nil {
276		return nil, nil, err
277	}
278
279	req, err := s.client.NewRequest("GET", u, nil)
280	if err != nil {
281		return nil, nil, err
282	}
283
284	// TODO: remove custom Accept header when this API fully launches.
285	req.Header.Set("Accept", mediaTypeGitSigningPreview)
286
287	var commits []*RepositoryCommit
288	resp, err := s.client.Do(ctx, req, &commits)
289	if err != nil {
290		return nil, resp, err
291	}
292
293	return commits, resp, nil
294}
295
296// ListFiles lists the files in a pull request.
297//
298// GitHub API docs: https://developer.github.com/v3/pulls/#list-pull-requests-files
299func (s *PullRequestsService) ListFiles(ctx context.Context, owner string, repo string, number int, opt *ListOptions) ([]*CommitFile, *Response, error) {
300	u := fmt.Sprintf("repos/%v/%v/pulls/%d/files", owner, repo, number)
301	u, err := addOptions(u, opt)
302	if err != nil {
303		return nil, nil, err
304	}
305
306	req, err := s.client.NewRequest("GET", u, nil)
307	if err != nil {
308		return nil, nil, err
309	}
310
311	var commitFiles []*CommitFile
312	resp, err := s.client.Do(ctx, req, &commitFiles)
313	if err != nil {
314		return nil, resp, err
315	}
316
317	return commitFiles, resp, nil
318}
319
320// IsMerged checks if a pull request has been merged.
321//
322// GitHub API docs: https://developer.github.com/v3/pulls/#get-if-a-pull-request-has-been-merged
323func (s *PullRequestsService) IsMerged(ctx context.Context, owner string, repo string, number int) (bool, *Response, error) {
324	u := fmt.Sprintf("repos/%v/%v/pulls/%d/merge", owner, repo, number)
325	req, err := s.client.NewRequest("GET", u, nil)
326	if err != nil {
327		return false, nil, err
328	}
329
330	resp, err := s.client.Do(ctx, req, nil)
331	merged, err := parseBoolResponse(err)
332	return merged, resp, err
333}
334
335// PullRequestMergeResult represents the result of merging a pull request.
336type PullRequestMergeResult struct {
337	SHA     *string `json:"sha,omitempty"`
338	Merged  *bool   `json:"merged,omitempty"`
339	Message *string `json:"message,omitempty"`
340}
341
342// PullRequestOptions lets you define how a pull request will be merged.
343type PullRequestOptions struct {
344	CommitTitle string // Extra detail to append to automatic commit message. (Optional.)
345	SHA         string // SHA that pull request head must match to allow merge. (Optional.)
346
347	// The merge method to use. Possible values include: "merge", "squash", and "rebase" with the default being merge. (Optional.)
348	MergeMethod string
349}
350
351type pullRequestMergeRequest struct {
352	CommitMessage string `json:"commit_message"`
353	CommitTitle   string `json:"commit_title,omitempty"`
354	MergeMethod   string `json:"merge_method,omitempty"`
355	SHA           string `json:"sha,omitempty"`
356}
357
358// Merge a pull request (Merge Button™).
359// commitMessage is the title for the automatic commit message.
360//
361// GitHub API docs: https://developer.github.com/v3/pulls/#merge-a-pull-request-merge-buttontrade
362func (s *PullRequestsService) Merge(ctx context.Context, owner string, repo string, number int, commitMessage string, options *PullRequestOptions) (*PullRequestMergeResult, *Response, error) {
363	u := fmt.Sprintf("repos/%v/%v/pulls/%d/merge", owner, repo, number)
364
365	pullRequestBody := &pullRequestMergeRequest{CommitMessage: commitMessage}
366	if options != nil {
367		pullRequestBody.CommitTitle = options.CommitTitle
368		pullRequestBody.MergeMethod = options.MergeMethod
369		pullRequestBody.SHA = options.SHA
370	}
371	req, err := s.client.NewRequest("PUT", u, pullRequestBody)
372	if err != nil {
373		return nil, nil, err
374	}
375
376	mergeResult := new(PullRequestMergeResult)
377	resp, err := s.client.Do(ctx, req, mergeResult)
378	if err != nil {
379		return nil, resp, err
380	}
381
382	return mergeResult, resp, nil
383}
384