1############
2Issue boards
3############
4
5Boards
6======
7
8Boards are a visual representation of existing issues for a project or a group.
9Issues can be moved from one list to the other to track progress and help with
10priorities.
11
12Reference
13---------
14
15* v4 API:
16
17  + :class:`gitlab.v4.objects.ProjectBoard`
18  + :class:`gitlab.v4.objects.ProjectBoardManager`
19  + :attr:`gitlab.v4.objects.Project.boards`
20  + :class:`gitlab.v4.objects.GroupBoard`
21  + :class:`gitlab.v4.objects.GroupBoardManager`
22  + :attr:`gitlab.v4.objects.Group.boards`
23
24* GitLab API:
25
26  + https://docs.gitlab.com/ce/api/boards.html
27  + https://docs.gitlab.com/ce/api/group_boards.html
28
29Examples
30--------
31
32Get the list of existing boards for a project or a group::
33
34    # item is a Project or a Group
35    boards = project_or_group.boards.list()
36
37Get a single board for a project or a group::
38
39    board = project_or_group.boards.get(board_id)
40
41Create a board::
42
43    board = project_or_group.boards.create({'name': 'new-board'})
44
45.. note:: Board creation is not supported in the GitLab CE edition.
46
47Delete a board::
48
49    board.delete()
50    # or
51    project_or_group.boards.delete(board_id)
52
53.. note:: Board deletion is not supported in the GitLab CE edition.
54
55Board lists
56===========
57
58Boards are made of lists of issues. Each list is associated to a label, and
59issues tagged with this label automatically belong to the list.
60
61Reference
62---------
63
64* v4 API:
65
66  + :class:`gitlab.v4.objects.ProjectBoardList`
67  + :class:`gitlab.v4.objects.ProjectBoardListManager`
68  + :attr:`gitlab.v4.objects.ProjectBoard.lists`
69  + :class:`gitlab.v4.objects.GroupBoardList`
70  + :class:`gitlab.v4.objects.GroupBoardListManager`
71  + :attr:`gitlab.v4.objects.GroupBoard.lists`
72
73* GitLab API:
74
75  + https://docs.gitlab.com/ce/api/boards.html
76  + https://docs.gitlab.com/ce/api/group_boards.html
77
78Examples
79--------
80
81List the issue lists for a board::
82
83    b_lists = board.lists.list()
84
85Get a single list::
86
87    b_list = board.lists.get(list_id)
88
89Create a new list::
90
91    # First get a ProjectLabel
92    label = get_or_create_label()
93    # Then use its ID to create the new board list
94    b_list = board.lists.create({'label_id': label.id})
95
96Change a list position. The first list is at position 0. Moving a list will
97set it at the given position and move the following lists up a position::
98
99    b_list.position = 2
100    b_list.save()
101
102Delete a list::
103
104    b_list.delete()
105