| ... |
... |
@@ -6,9 +6,9 @@ For a detailed explanation of how to hack on BuildStream, please see the |
|
6
|
6
|
[CONTRIBUTING.rst](https://gitlab.com/BuildStream/buildstream/blob/master/CONTRIBUTING.rst) guide.
|
|
7
|
7
|
|
|
8
|
8
|
|
|
9
|
|
-## BuildStream on Gitlab: policies
|
|
|
9
|
+## Use of Gitlab features
|
|
10
|
10
|
|
|
11
|
|
-We intend to make use of some of GitLab's features in order to structure the
|
|
|
11
|
+We intend to make use of some of Gitlab's features in order to structure the
|
|
12
|
12
|
activity of the project. In doing so we are trying to achieve the
|
|
13
|
13
|
following goals:
|
|
14
|
14
|
|
| ... |
... |
@@ -25,182 +25,91 @@ and value all contributions to the project! |
|
25
|
25
|
|
|
26
|
26
|
### Milestones
|
|
27
|
27
|
|
|
28
|
|
-Milestone on Gitlab matches relevant events that are related with time frames like release cycles and events. The only current global milestones across the entire BuildStream Group are release cycles.
|
|
|
28
|
+[Milestones](https://gitlab.com/groups/BuildStream/-/milestones) on Gitlab denote
|
|
|
29
|
+time-bound periods: we are using milestones to structure releases and events.
|
|
|
30
|
+See all group level milestones [here](https://gitlab.com/groups/BuildStream/-/milestones).
|
|
29
|
31
|
|
|
30
|
|
-General description of how milestones work on Gitlab: <https://docs.gitlab.com/ee/user/project/milestones/>
|
|
31
|
|
-
|
|
32
|
|
-Global milestones on Gitlab: <https://gitlab.com/groups/BuildStream/-/milestones>
|
|
|
32
|
+Note: milestones are not to be confused with [Epics](https://docs.gitlab.com/ee/user/group/epics)
|
|
|
33
|
+which allow you to group sub tasks into an overall goal.
|
|
|
34
|
+Epics are currently not available for us to use in this version of Gitlab.
|
|
33
|
35
|
|
|
34
|
36
|
|
|
35
|
37
|
|
|
36
|
38
|
### Labels
|
|
37
|
39
|
|
|
38
|
|
-Labels allow us to structure, filter and visualise some of the Gitlab elements in different ways. Some of those labels apply to the entire BuildStream group and some only apply to specific repositories (projects).
|
|
|
40
|
+[Labels](https://docs.gitlab.com/ee/user/project/labels.html) allow us to
|
|
|
41
|
+filter tickets (ie, 'issues' in Gitlab terminology) in useful ways.
|
|
|
42
|
+
|
|
|
43
|
+ Labels add complexity and effort as they grow in number, so the ideal approach
|
|
|
44
|
+ is to have the minimum possible but to use them consistently. Sadly, we currenlty have
|
|
|
45
|
+ far too many labels, so if you want to add a new one, please do discuss this the [mailing
|
|
|
46
|
+ list](https://mail.gnome.org/mailman/listinfo/buildstream-list) first.
|
|
39
|
47
|
|
|
40
|
|
-Check the description of labels on Gitlab: <https://docs.gitlab.com/ee/user/project/labels.html>
|
|
|
48
|
+We have both [global scale labels](https://gitlab.com/groups/BuildStream/-/labels) and
|
|
|
49
|
+[BuildStream project specific labels](https://gitlab.com/BuildStream/buildstream/labels).
|
|
41
|
50
|
|
|
42
|
|
-Check the global scale labels: <https://gitlab.com/groups/BuildStream/-/labels>
|
|
|
51
|
+When raising an issue, please consider which labels are appropriate:
|
|
43
|
52
|
|
|
44
|
|
-The global ones are:
|
|
|
53
|
+* Topic labels: each repository has its own labels that allow you to structure tickets per topic. For example, there's a 'Documentation' label for tasks related to documentation.
|
|
45
|
54
|
|
|
46
|
|
-* Status scale:
|
|
47
|
|
- * Backlog: default state on Gitlab so no label needed.
|
|
48
|
|
- * Todo: processed elements that should be done in the future.
|
|
49
|
|
- * Doing: WIP
|
|
50
|
|
- * Review: items that are under review once the developer or contributor has finished it.
|
|
51
|
|
- * Closed: items that has been processed and canceled, finished or no longer apply. Default state on Gitlab so no label needed.
|
|
52
|
|
-* Severity scale (these labels are prioritized):
|
|
|
55
|
+* Severity scale: please apply the below in order to get the attention of the core development team, as these labels are prioritized in weekly meetings:
|
|
53
|
56
|
* No label: unprocessed item, no or low priority.
|
|
54
|
57
|
* Important: default severity for processed items that should be executed/considered.
|
|
55
|
58
|
* Urgent: to pay attention in the immediate future when possible.
|
|
56
|
59
|
* Critical: topics that require attention immediately when possible.
|
|
57
|
|
-* Impact scale: this scale is restricted to the buildstream project for now.
|
|
58
|
|
- * high_impact: the crash/feature/task takes place frequently or is a recurrent one and has a significant impact on users everyday or key work.
|
|
59
|
|
- * No label: the crash/feature/task is infrequent or hard to reproduce and the impact on the users is low or hard to determine.
|
|
60
|
|
-* Topic labels: each repository has its own labels that allow to structure tickets per topic.
|
|
|
60
|
+
|
|
61
|
61
|
|
|
62
|
|
-Check the buildstream project specific topic labels: <https://gitlab.com/BuildStream/buildstream/labels>
|
|
63
|
62
|
|
|
64
|
|
-In order to propose new labels or a change in the current ones, please send a mail to the mailing list or add a ticket in the alignment repo: <https://gitlab.com/BuildStream/nosoftware/alignment/issues>
|
|
65
|
63
|
|
|
66
|
64
|
### Issue Boards
|
|
67
|
65
|
|
|
68
|
|
-Boards allow anybody interested in BuildStream to visualise and manage (workflow) issues in a simple way. BuildStream has boards at global level (group), subgroup level (nosoftware) and project level.
|
|
|
66
|
+[Issue boards](https://docs.gitlab.com/ee/user/project/issue_board.html) allow anybody interested in BuildStream to visualise and manage issues in a simple way.
|
|
|
67
|
+There are [Global level boards](https://gitlab.com/groups/BuildStream/-/boards/580444?milestone_title=BuildStream_v1.1>&=) and
|
|
|
68
|
+[BuildStream project specific boards](https://gitlab.com/BuildStream/buildstream/boards/580451?milestone_title=BuildStream_v1.1>&=).
|
|
|
69
|
+There is a drop down menu allowing you to select every available board. The most relevant to most people is the [Status-All Board](https://gitlab.com/BuildStream/buildstream/boards/134373).
|
|
69
|
70
|
|
|
70
|
|
-* Check the description of labels on Gitlab: <https://about.gitlab.com/features/issueboard/>
|
|
71
|
|
-* Check the global boards: <https://gitlab.com/groups/BuildStream/-/boards/580444?milestone_title=BuildStream_v1.1>&=
|
|
72
|
|
-* Check the buildstream repo specific boards: <https://gitlab.com/BuildStream/buildstream/boards/580451?milestone_title=BuildStream_v1.1>&=
|
|
73
|
|
-* There is a menu in the above pages to select every available board.
|
|
|
71
|
+Issues start life in the ``Backlog`` column by default, and we move them into
|
|
|
72
|
+ ``ToDo`` when we aim to complete them soon. ``Doing`` is only for when an item is
|
|
|
73
|
+ currently being worked on. When on the Board view, dragging and dropping an issue from
|
|
|
74
|
+ column to column automatically adjusts the relevant labels.
|
|
74
|
75
|
|
|
75
|
|
-There are three main groups of boards:
|
|
|
76
|
+There are two main types of boards:
|
|
76
|
77
|
|
|
77
|
|
-* Status boards: allow anybody to visualize Work in Progress (WIP) and move tickets from one status to another one so there is no need to manually change the labels, including when a ticket is closed.
|
|
78
|
|
-* Severity boards: allow anybody to visualize how relevant the tickets are for developers, based on a variety of criteria that ends up on a notion of priority. It also is useful to move the tickets from one severity state to another one so there is no need to manually change the labels, including when a ticket is closed.
|
|
79
|
|
-* Other boards: there are other kind of boards for specific use cases.
|
|
|
78
|
+* Status boards: shows WIP visibility of all items currently in flight.
|
|
|
79
|
+* Severity boards: shows relevant tickets for developers, based on priority, eg critical bugs.
|
|
80
|
80
|
|
|
81
|
81
|
### Templates
|
|
82
|
82
|
|
|
83
|
|
-The usage of issues and merge requests templates allow community members to understand which information is required for developers and contributors to fully understand and process the bug/task/request adequately. Templates are assigned per project/repo and need to be selected when creating an issue or merge request.
|
|
84
|
|
-
|
|
85
|
|
-
|
|
86
|
|
-Check the information about templates from Gitlab: <https://docs.gitlab.com/ee/user/project/description_templates.html>
|
|
87
|
|
-
|
|
88
|
|
-Check the templates used at BuildStream:
|
|
89
|
|
-* buildstream repo/project templates:
|
|
90
|
|
- * Default template:
|
|
91
|
|
- * Bug template:
|
|
92
|
|
- * Merge request template:
|
|
93
|
|
-* alignment/communication repos templates:
|
|
94
|
|
- * task template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/task.md
|
|
95
|
|
- * bug template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/bug.md
|
|
96
|
|
- * Merge request template: https://gitlab.com/BuildStream/buildstream/blob/master/.gitlab/merge_request_templates/bst_merge_request.md
|
|
97
|
|
-
|
|
98
|
|
-### Technical/engineering tasks: best practices.
|
|
99
|
|
-
|
|
100
|
|
-These are the best practices that are applied to Gitlab at BuildStream in relation with bugs and tasks. Please read them carefully and try to apply them.
|
|
101
|
|
-
|
|
102
|
|
-#### Open/create a technical issue
|
|
103
|
|
-
|
|
104
|
|
-In order to open a new task the best place is the green button at this page: <https://gitlab.com/BuildStream/buildstream/issues>. Please follow these considerations:
|
|
105
|
|
-* Use the default template.
|
|
106
|
|
-* Fill out the information required.
|
|
107
|
|
- * Select the milestone/version affected or related with the task.
|
|
108
|
|
- * If the ticket is related with the current milestone/version and older, please leave the default option.
|
|
109
|
|
-* Save the ticket.
|
|
110
|
|
-* Apply further metadata if you are sure about which labels to use.
|
|
111
|
|
- * Leave the Assignee blank unless you know who is the person responsible for that issue.
|
|
112
|
|
- * Consider applying topic labels if are familiar with them.
|
|
113
|
|
- * If the issue is just a breakdown of another task, please consider applying the same topic labels.
|
|
114
|
|
-* Further considerations:
|
|
115
|
|
- * If you want to notify somebody about the ticket, please add his/her name as first comment. Try to avoid naming people for notification reasons in the ticket description.
|
|
116
|
|
- * It is extremely useful that you use the Related Topics field adding:
|
|
117
|
|
- * #"ticket id" if the ticket you just created is related with another ticket from the same repo.
|
|
118
|
|
- * Relative link if the ticket you just created is related with a ticket from the BuildStream group or a different group within gitlab.com.
|
|
119
|
|
- * A full URL if the ticket is related with a gitlab ticket under a different domain.
|
|
120
|
|
- * The MR associated with the ticket. Please do not forget this.
|
|
121
|
|
- * If your issue remains unprocessed after a few days/weeks, please ask through the project mailing list about it. It should be the exception but it might have been overlooked or remain unnoticed.
|
|
122
|
|
-
|
|
123
|
|
-#### Update an engineering task / ticket
|
|
124
|
|
-
|
|
125
|
|
-Assuming the bulk of the work on engineering tasks takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
|
|
126
|
|
-* Assign the ticket to you when you start working on it. More than one person can be assigned to a single task.
|
|
127
|
|
-* Assign the correct milestone and labels if they are not in place already.
|
|
128
|
|
- * If the task is being executed, please assign the label "Doing", removing the "ToDo" label.
|
|
129
|
|
- * Fill out the "Related Issues" field if there are other bugs or tasks that have a dependency or are related with the one it is being executed.
|
|
130
|
|
-* Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
|
|
131
|
|
- * This is very important for others to follow up your work.
|
|
132
|
|
-
|
|
133
|
|
-#### Close an engineering task
|
|
134
|
|
-
|
|
135
|
|
-(coming soon)
|
|
136
|
|
-
|
|
137
|
|
-### Bugs: best practices
|
|
138
|
|
-
|
|
139
|
|
-#### Open/create a bug
|
|
140
|
|
-
|
|
141
|
|
-In order to open a new bug the best place is the green button at this page: <https://gitlab.com/BuildStream/buildstream/issues>. Please follow these considerations:
|
|
142
|
|
-* Use the Bug template. Choose it from the template menu when creating a new bug.
|
|
143
|
|
-* Fill out the information required. This is extremely important in the case of bugs. Developers will need to reproduce it in order to process it adequately.
|
|
144
|
|
- * Please fill out the milestone/version affected.
|
|
145
|
|
- * Refer to milestones adding the "%" symbol and selecting from the available options.
|
|
146
|
|
- * If the affected version is the current
|
|
147
|
|
-* Save the ticket.
|
|
148
|
|
-* Apply further metadata if you are sure about which labels to use.
|
|
149
|
|
- * If the bug shows up frequently and has a big impact in your everyday work or is present while performing a key action, please consider applying the label: high_impact. Otherwise, please do not apply it.
|
|
150
|
|
- * If you know the person responsible for analyzing/ processing the bug, please assign the bug to that person. Otherwise, leave it unassigned. The same policy applies to any topic labels.
|
|
151
|
|
- * Please remember that the Bug template already have the label "bug" assigned by default.
|
|
152
|
|
- * Do not assign any severity or status label unless you are going to work on it yourself. In case of doubt, apply the lowest value.
|
|
153
|
|
-* Further considerations:
|
|
154
|
|
- * Please refer to the considerations made for issues since they also apply to this case.
|
|
155
|
|
-
|
|
156
|
|
-#### Update a bug
|
|
157
|
|
-
|
|
158
|
|
-Assuming the bulk of the work on bugs takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
|
|
159
|
|
-* Assign the bug to you. More than one person can be assigned to a single bug.
|
|
160
|
|
-* Assign the correct milestone and labels if they are not in place already.
|
|
161
|
|
- * If the bug is being investigated or resolved, please assign the label "Doing", removing the "ToDo" label.
|
|
162
|
|
- * Fill out the "Related Issues" field if there are other bugs or tasks that have a dependency or are related with the one it is being executed.
|
|
163
|
|
-* Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
|
|
164
|
|
- * This is very important for others to follow up your work.
|
|
165
|
|
-
|
|
166
|
|
-## Merge requests: best practices.
|
|
167
|
|
-
|
|
168
|
|
-These are the different policies that the project applies to merge requests.
|
|
|
83
|
+[Templates](https://docs.gitlab.com/ee/user/project/description_templates.html) are a good way to prompt users for certain information.
|
|
169
|
84
|
|
|
170
|
|
-#### Close a Bug
|
|
|
85
|
+When opening a new isue or merge request, please follow the template guideline, and include as much information as possible.
|
|
171
|
86
|
|
|
172
|
|
-(coming soon)
|
|
|
87
|
+We have two templates for issues:
|
|
173
|
88
|
|
|
174
|
|
-### Merge requests (MR): best practices
|
|
|
89
|
+* Bugs
|
|
|
90
|
+* Tasks
|
|
175
|
91
|
|
|
176
|
|
-#### Open/create a merge request
|
|
|
92
|
+### Raising a ticket (ie, gitlab issue): best practice
|
|
177
|
93
|
|
|
178
|
|
-Please read carefully the following policies before opening a new merge request. The best place to create a new merge request is this page: <https://gitlab.com/BuildStream/buildstream/merge_requests>. Please follow these considerations:
|
|
179
|
|
-* Use the default template.
|
|
180
|
|
-* Fill out the information required.
|
|
181
|
|
- * As in the case of the bugs, please be verbose. It will make the review process simpler and faster.
|
|
182
|
|
-* Save the merge request.
|
|
183
|
|
-* Apply further metadata if you are sure about which labels to use.
|
|
184
|
|
- * It is extremely important that you add to the merge request description the issue id/number this merge request affects to.
|
|
185
|
|
- * It is important to assign the merge request to a reviewer if you know who that person is. Please use the buildstream IRC channel to find out who that person is, if you can. Otherwise, leave it unassigned.
|
|
186
|
|
-* Further considerations:
|
|
187
|
|
- * We do not apply for now status labels to merge requests.
|
|
188
|
|
- * Severity labels will be applied in very specific cases only.
|
|
189
|
|
- * If you want to notify somebody about the merge request, please add his/her name as first comment, starting by the character "@". Try to avoid naming people for notification reasons in the merge request description field.
|
|
190
|
|
- * If your merge request remains unprocessed for over a week, please ask through IRC (#buildstream in irc.gonme.org) about it. It should be the exception but it might have been overlooked, remain unnoticed or the default reviewer is overloaded.
|
|
|
94
|
+- When raising an issue, please:
|
|
|
95
|
+
|
|
|
96
|
+ - check to see if there already is an issue to cover this task (if not then
|
|
|
97
|
+ raise a new one)
|
|
|
98
|
+ - assign the appropriate label or labels (tip: the vast majority of issues
|
|
|
99
|
+ raised will be either an enhancement or a bug)
|
|
|
100
|
+ - consider which release (ie, milestone) this ticket falls under
|
|
|
101
|
+
|
|
|
102
|
+- If you plan to work on an issue, please:
|
|
191
|
103
|
|
|
192
|
|
-#### Update a merge request
|
|
193
|
|
-
|
|
194
|
|
-It is strongly recommended that you follow these advices:
|
|
195
|
|
-* Assign the Merge Request to you when you start working on it. Please remember than more than one person can be assigned to the MR.
|
|
196
|
|
-* Assign the correct milestone and labels if they are not in place already.
|
|
197
|
|
- * If the MR is in progress, please assign to it the label "Doing", removing the "ToDo" label if present.
|
|
198
|
|
- * every MR should be related in the description field to at least one engineering task or bug. Please check this is the case.
|
|
199
|
|
-* Update the MR when a relevant event takes place.
|
|
|
104
|
+ - self-assign the ticket
|
|
|
105
|
+ - ensure the ticket is in the ``ToDo`` column of the [Status-All Board](https://gitlab.com/BuildStream/buildstream/boards/134373) if you aim to
|
|
|
106
|
+ work on it soon but are not yet working on it, and
|
|
|
107
|
+ the ``Doing`` column if you are working on it currently.
|
|
200
|
108
|
|
|
201
|
|
-#### Close a Merge Request
|
|
|
109
|
+- Please note that Gitlab issues are for either 'tasks' or 'bugs' - ie not for
|
|
|
110
|
+ long discussions (where the mailing list is a better choice) or for ranting,
|
|
|
111
|
+ for example.
|
|
202
|
112
|
|
|
203
|
|
-(coming soon)
|
|
204
|
113
|
|
|
205
|
114
|
## Roadmap policies
|
|
206
|
115
|
|
