BuildStream_policies.md 12.8 KB
Newer Older
1 2
# BuildStream policies

3 4
## Hacking on BuildStream

5
Every policy related with hacking or developing BuildStream is described in the technical documentation: <https://buildstream.gitlab.io/buildstream/HACKING.html>
6

7
## BuildStream on Gitlab: policies
8 9 10 11 12 13 14

Description of the main elements on Gitlab used at BuildStream.

### Milestones

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.

15
General description of how milestones work on Gitlab: <https://docs.gitlab.com/ee/user/project/milestones/>
16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32

Global milestones on Gitlab: <https://gitlab.com/groups/BuildStream/-/milestones>

### Labels

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).

Check the description of labels on Gitlab: <https://docs.gitlab.com/ee/user/project/labels.html>

Check the global scale labels: <https://gitlab.com/groups/BuildStream/-/labels>

The global ones are:

* Status scale:
	* Backlog: default state on Gitlab so no label needed.
	* Todo: processed elements that should be done in the future.
	* Doing: WIP
33
	* Review: items that are under review once the developer or contributor has finished it. 
34 35
	* Closed: items that has been processed and canceled, finished or no longer apply. Default state on Gitlab so no label needed.
* Severity scale (these labels are prioritized):
36 37 38 39 40
    * No label: unprocessed item, no or low priority.
    * Important: default severity for processed items that should be executed/considered.
    * Urgent: to pay attention in the immediate future when possible.
    * Critical: topics that require attention immediately when possible.
* Impact scale: this scale is restricted to the buildstream project for now.
41
	* 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.
42
	* No label: the crash/feature/task is infrequent or hard to reproduce and the impact on the users is low or hard to determine.
43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73
* Topic labels: each repository has its own labels that allow to structure tickets per topic.

Check the buildstream project specific topic labels: <https://gitlab.com/BuildStream/buildstream/labels>

Check the nosoftware repos topic labels

* communication project labels: <https://gitlab.com/BuildStream/nosoftware/communication/labels>
* alignment project labels: <https://gitlab.com/BuildStream/nosoftware/alignment/labels>

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>

### Issue Boards

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.

* Check the description of labels on Gitlab: <https://about.gitlab.com/features/issueboard/>
* Check the global boards: <https://gitlab.com/groups/BuildStream/-/boards/580444?milestone_title=BuildStream_v1.1>&= 
* Check the buildstream repo specific boards: <https://gitlab.com/BuildStream/buildstream/boards/580451?milestone_title=BuildStream_v1.1>&=
* There is a menu in the above pages to select every available board.

There are three main groups of boards:

* 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.
* 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.
* Other boards: there are other kind of boards for specific use cases.

### Templates

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.


74
Check the information about templates from Gitlab: <https://docs.gitlab.com/ee/user/project/description_templates.html>
75

76 77
Check the templates used at BuildStream:
* buildstream repo/project templates:
78 79
	* Default template:
	* Bug template:
80 81 82 83
	* Merge request template:
* alignment/communication repos templates:
    * task template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/task.md
    * bug template: https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/.gitlab/issue_templates/bug.md
84
    * Merge request template: https://gitlab.com/BuildStream/buildstream/blob/master/.gitlab/merge_request_templates/bst_merge_request.md
85

86
### Technical/engineering tasks: best practices.
87

88 89
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.

90
#### Open/create a technical issue
91

92
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:
93 94 95 96 97 98 99 100 101 102 103 104 105 106 107
* Use the default template.
* Fill out the information required.
	* Select the milestone/version affected or related with the task.
	* If the ticket is related with the current milestone/version and older, please leave the default option.
* Save the ticket.
* Apply further metadata if you are sure about which labels to use.
	* Leave the Assignee blank unless you know who is the person responsible for that issue.
	* Consider applying topic labels if are familiar with them.
		* If the issue is just a breakdown of another task, please consider applying the same topic labels.
* Further considerations:
	* 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.
	* It is extremely useful that you use the Related Topics field adding:
		* #"ticket id" if the ticket you just created is related with another ticket from the same repo.
		* Relative link if the ticket you just created is related with a ticket from the BuildStream group or a different group within gitlab.com.
		* A full URL if the ticket is related with a gitlab ticket under a different domain.
108
		* The MR associated with the ticket. Please do not forget this.
109 110
	* 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.  

111
#### Update an engineering task / ticket
112

113 114 115 116 117 118 119 120
Assuming the bulk of the work on engineering tasks takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
* Assign the ticket to you when you start working on it. More than one person can be assigned to a single task.
* Assign the correct milestone and labels if they are not in place already.
   * If the task is being executed, please assign the label "Doing", removing the "ToDo" label.
   * 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.
* Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
    * This is very important for others to follow up your work.

121
#### Close an engineering task
122 123 124

(coming soon)
    
125
### Bugs: best practices
126
    
127
#### Open/create a bug
128 129

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:
130 131 132 133 134 135 136 137 138 139 140 141 142 143
* Use the Bug template. Choose it from the template menu when creating a new bug.
* 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.
	* Please fill out the milestone/version affected. 
		* Refer to milestones adding the "%" symbol and selecting from the available options.
		* If the affected version is the current
* Save the ticket.
* Apply further metadata if you are sure about which labels to use.
	* 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.
	* 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.
	* Please remember that the Bug template already have the label "bug" assigned by default.
	* 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. 
* Further considerations:
	* Please refer to the considerations made for issues since they also apply to this case.

144
#### Update a bug
145

146 147 148 149 150 151 152 153
Assuming the bulk of the work on bugs takes places on Merge Requests (code), it is strongly recommended that you follow these advices:
* Assign the bug to you. More than one person can be assigned to a single bug.
* Assign the correct milestone and labels if they are not in place already.
   * If the bug is being investigated or resolved, please assign the label "Doing", removing the "ToDo" label.
   * 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.
* Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days.
    * This is very important for others to follow up your work.
	
154 155
## Merge requests: best practices.

156 157
These are the different policies that the project applies to merge requests.

158
#### Close a Bug
159 160 161

(coming soon)

162
### Merge requests (MR): best practices
163

164
#### Open/create a merge request
165

166
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:
167 168 169 170 171
* Use the default template.
* Fill out the information required.
	* As in the case of the bugs, please be verbose. It will make the review process simpler and faster.
* Save the merge request.
* Apply further metadata if you are sure about which labels to use.
172
	* It is extremely important that you add to the merge request description the issue id/number this merge request affects to.
173 174 175 176 177
	* 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.
* Further considerations:
	* We do not apply for now status labels to merge requests.
	* Severity labels will be applied in very specific cases only.
	* 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.
178
	* 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.
179

180
#### Update a merge request
181 182 183 184 185 186 187
	
It is strongly recommended that you follow these advices:
* 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.
* Assign the correct milestone and labels if they are not in place already.
   * If the MR is in progress, please assign to it the label "Doing", removing the "ToDo" label if present.
   * every MR should be related in the description field to at least one engineering task or bug. Please check this is the case. 
* Update the MR when a relevant event takes place.
188 189 190 191 192

#### Close a Merge Request

(coming soon)

193
## Roadmap policies
194
	
195 196
## Suggest improvements or additions to the BuildStream policy

197
If the suggestion refers to coding or hacking the BuildStream code related policies, please create a MR to the technical documentation: <https://gitlab.com/BuildStream/buildstream/tree/master/doc/source>
198

199
If the suggestion refers to how to manage tickets, bugs or merge requests or any other topic not directly related with coding, please create a MR to this policy instead of editing this wiki page: <https://gitlab.com/BuildStream/nosoftware/alignment/blob/master/BuildStream_policies.md>
200

201
You can always send the proposal to the <mailto:buildstream-list@gnome.org> mailing list if any of the options above fits or you are unsure about what to do.
202