Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
Gauvain Pocentek
committed
May 27, 2018
1 parent
7025743
commit 63a4c7c
Showing
1 changed file
with
107 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,107 @@ | ||
########### | ||
Discussions | ||
########### | ||
|
||
Discussions organize the notes in threads. See the :ref:`project-notes` chapter | ||
for more information about notes. | ||
|
||
Discussions are available for project issues, merge requests, snippets and | ||
commits. | ||
|
||
Reference | ||
========= | ||
|
||
* v4 API: | ||
|
||
Issues: | ||
|
||
+ :class:`gitlab.v4.objects.ProjectIssueDiscussion` | ||
+ :class:`gitlab.v4.objects.ProjectIssueDiscussionManager` | ||
+ :class:`gitlab.v4.objects.ProjectIssueDiscussionNote` | ||
+ :class:`gitlab.v4.objects.ProjectIssueDiscussionNoteManager` | ||
+ :attr:`gitlab.v4.objects.ProjectIssue.notes` | ||
|
||
MergeRequests: | ||
|
||
+ :class:`gitlab.v4.objects.ProjectMergeRequestDiscussion` | ||
+ :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionManager` | ||
+ :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNote` | ||
+ :class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNoteManager` | ||
+ :attr:`gitlab.v4.objects.ProjectMergeRequest.notes` | ||
|
||
Snippets: | ||
|
||
+ :class:`gitlab.v4.objects.ProjectSnippetDiscussion` | ||
+ :class:`gitlab.v4.objects.ProjectSnippetDiscussionManager` | ||
+ :class:`gitlab.v4.objects.ProjectSnippetDiscussionNote` | ||
+ :class:`gitlab.v4.objects.ProjectSnippetDiscussionNoteManager` | ||
+ :attr:`gitlab.v4.objects.ProjectSnippet.notes` | ||
|
||
* GitLab API: https://docs.gitlab.com/ce/api/discussions.html | ||
|
||
Examples | ||
======== | ||
|
||
List the discussions for a resource (issue, merge request, snippet or commit):: | ||
|
||
discussions = resource.discussions.list() | ||
|
||
Get a single discussion:: | ||
|
||
discussion = resource.discussion.get(discussion_id) | ||
|
||
You can access the individual notes in the discussion through the ``notes`` | ||
attribute. It holds a list of notes in chronological order:: | ||
|
||
# ``resource.notes`` is a DiscussionNoteManager, so we need to get the | ||
# object notes using ``attributes`` | ||
for note in discussion.attributes['notes']: | ||
print(note['body']) | ||
|
||
.. note:: | ||
|
||
The notes are dicts, not objects. | ||
|
||
You can add notes to existing discussions:: | ||
|
||
new_note = discussion.notes.create({'body': 'Episode IV: A new note'}) | ||
|
||
You can get and update a single note using the ``*DiscussionNote`` resources:: | ||
|
||
discussion = resource.discussion.get(discussion_id) | ||
# Get the latest note's id | ||
note_id = discussion.attributes['note'][-1]['id'] | ||
last_note = discussion.notes.get(note_id) | ||
last_note.body = 'Updated comment' | ||
last_note.save() | ||
|
||
Create a new discussion:: | ||
|
||
discussion = resource.discussion.create({'body': 'First comment of discussion'}) | ||
|
||
You can comment on merge requests and commit diffs. Provide the ``position`` | ||
dict to define where the comment should appear in the diff:: | ||
|
||
mr_diff = mr.diffs.get(diff_id) | ||
mr.discussions.create({'body': 'Note content', | ||
'position': { | ||
'base_sha': mr_diff.base_commit_sha, | ||
'start_sha': mr_diff.start_commit_sha, | ||
'head_sha': mr_diff.head_commit_sha, | ||
'position_type': 'text', | ||
'new_line': 1, | ||
'old_path': 'README.rst', | ||
'new_path': 'README.rst'} | ||
}) | ||
|
||
Resolve / unresolve a merge request discussion:: | ||
|
||
mr_d = mr.discussions.get(d_id) | ||
mr_d.resolved = True # True to resolve, False to unresolve | ||
mr_d.save() | ||
|
||
Delete a comment:: | ||
|
||
discussions.notes.delete(note_id) | ||
# or | ||
note.delete() |