|
| 1 | +########### |
| 2 | +Discussions |
| 3 | +########### |
| 4 | + |
| 5 | +Discussions organize the notes in threads. See the:ref:`project-notes` chapter |
| 6 | +for more information about notes. |
| 7 | + |
| 8 | +Discussions are available for project issues, merge requests, snippets and |
| 9 | +commits. |
| 10 | + |
| 11 | +Reference |
| 12 | +========= |
| 13 | + |
| 14 | +* v4 API: |
| 15 | + |
| 16 | + Issues: |
| 17 | + |
| 18 | + +:class:`gitlab.v4.objects.ProjectIssueDiscussion` |
| 19 | + +:class:`gitlab.v4.objects.ProjectIssueDiscussionManager` |
| 20 | + +:class:`gitlab.v4.objects.ProjectIssueDiscussionNote` |
| 21 | + +:class:`gitlab.v4.objects.ProjectIssueDiscussionNoteManager` |
| 22 | + +:attr:`gitlab.v4.objects.ProjectIssue.notes` |
| 23 | + |
| 24 | + MergeRequests: |
| 25 | + |
| 26 | + +:class:`gitlab.v4.objects.ProjectMergeRequestDiscussion` |
| 27 | + +:class:`gitlab.v4.objects.ProjectMergeRequestDiscussionManager` |
| 28 | + +:class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNote` |
| 29 | + +:class:`gitlab.v4.objects.ProjectMergeRequestDiscussionNoteManager` |
| 30 | + +:attr:`gitlab.v4.objects.ProjectMergeRequest.notes` |
| 31 | + |
| 32 | + Snippets: |
| 33 | + |
| 34 | + +:class:`gitlab.v4.objects.ProjectSnippetDiscussion` |
| 35 | + +:class:`gitlab.v4.objects.ProjectSnippetDiscussionManager` |
| 36 | + +:class:`gitlab.v4.objects.ProjectSnippetDiscussionNote` |
| 37 | + +:class:`gitlab.v4.objects.ProjectSnippetDiscussionNoteManager` |
| 38 | + +:attr:`gitlab.v4.objects.ProjectSnippet.notes` |
| 39 | + |
| 40 | +* GitLab API: https://docs.gitlab.com/ce/api/discussions.html |
| 41 | + |
| 42 | +Examples |
| 43 | +======== |
| 44 | + |
| 45 | +List the discussions for a resource (issue, merge request, snippet or commit):: |
| 46 | + |
| 47 | + discussions = resource.discussions.list() |
| 48 | + |
| 49 | +Get a single discussion:: |
| 50 | + |
| 51 | + discussion = resource.discussion.get(discussion_id) |
| 52 | + |
| 53 | +You can access the individual notes in the discussion through the ``notes`` |
| 54 | +attribute. It holds a list of notes in chronological order:: |
| 55 | + |
| 56 | + # ``resource.notes`` is a DiscussionNoteManager, so we need to get the |
| 57 | + # object notes using ``attributes`` |
| 58 | + for note in discussion.attributes['notes']: |
| 59 | + print(note['body']) |
| 60 | + |
| 61 | +..note:: |
| 62 | + |
| 63 | + The notes are dicts, not objects. |
| 64 | + |
| 65 | +You can add notes to existing discussions:: |
| 66 | + |
| 67 | + new_note = discussion.notes.create({'body': 'Episode IV: A new note'}) |
| 68 | + |
| 69 | +You can get and update a single note using the ``*DiscussionNote`` resources:: |
| 70 | + |
| 71 | + discussion = resource.discussion.get(discussion_id) |
| 72 | + # Get the latest note's id |
| 73 | + note_id = discussion.attributes['note'][-1]['id'] |
| 74 | + last_note = discussion.notes.get(note_id) |
| 75 | + last_note.body = 'Updated comment' |
| 76 | + last_note.save() |
| 77 | + |
| 78 | +Create a new discussion:: |
| 79 | + |
| 80 | + discussion = resource.discussion.create({'body': 'First comment of discussion'}) |
| 81 | + |
| 82 | +You can comment on merge requests and commit diffs. Provide the ``position`` |
| 83 | +dict to define where the comment should appear in the diff:: |
| 84 | + |
| 85 | + mr_diff = mr.diffs.get(diff_id) |
| 86 | + mr.discussions.create({'body': 'Note content', |
| 87 | + 'position': { |
| 88 | + 'base_sha': mr_diff.base_commit_sha, |
| 89 | + 'start_sha': mr_diff.start_commit_sha, |
| 90 | + 'head_sha': mr_diff.head_commit_sha, |
| 91 | + 'position_type': 'text', |
| 92 | + 'new_line': 1, |
| 93 | + 'old_path': 'README.rst', |
| 94 | + 'new_path': 'README.rst'} |
| 95 | + }) |
| 96 | + |
| 97 | +Resolve / unresolve a merge request discussion:: |
| 98 | + |
| 99 | + mr_d = mr.discussions.get(d_id) |
| 100 | + mr_d.resolved = True # True to resolve, False to unresolve |
| 101 | + mr_d.save() |
| 102 | + |
| 103 | +Delete a comment:: |
| 104 | + |
| 105 | + discussions.notes.delete(note_id) |
| 106 | + # or |
| 107 | + note.delete() |
