Laurence/update policies
Description
I've heard complaints recently that people did not know how to follow the policies of the project related to Gitlab. People found the policies to be difficult to consume, so this MR is an attempt to simplify them and make them more accessible.
Proposed changes
Changes proposed in this merge request:
- Updates old HACKING links to CONTRIBUTING
- Cleans up all of the links to be neat hyperlinks in markdown format , instead of full links
- Massively reduces amount of text relating to templates and also opening / closing tickets
- Removes information about nosoftware labels
Note: I have left in there what I believe to be some outdated info on the severity labels and impact labels since Tristan changed them. However I'm not too sure how there are actually being used at the moment, so would appreciate some input there. The new world order for severity labels really does not make sense to me....perhaps we can consider changing it back...but that's a discussion for elsewhere....
Also, I think we may need to outline better how to flag a bug you are raising as 'high priority' so that the development team take a look at it.
Admittedly, some of the finer details have been removed. But I believe it is worth it in order to have a more accessible and easy to digest policy.
Gitlab issue this MR closes
No related issue - apologies, I forgot to raise an issue and just went straight into writing the patch.
Merge request reports
Activity
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. 14 35 15 General description of how milestones work on Gitlab: <https://docs.gitlab.com/ee/user/project/milestones/> 16 36 17 Global milestones on Gitlab: <https://gitlab.com/groups/BuildStream/-/milestones> 18 37 19 38 ### Labels 20 39 21 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 Additional labels only add value when they are used by all developers. When they are only partially used, in order to visualize what is happening, you leave things behind, so you need to add effort to structure WIP.
In addition, you make menus longer, required information to open bugs, for instance larger, documentation longer, info required to learn by new developers longer, scroll down in the label page, harder to visualise labels in the list view, add info required for templates.... small tiby additions here and there that ned up making the UI "too expensive to use" and tickets "too long to fill out properly", up to a point in which, multiplied by the number of developers, the number of seconds any dev. invest in the UI, and managers in keeping WIP clean. the cost is simply too high.
When people reach that point where management becomes a hurdle, people blames the tool and the solution is usually to change it. The root cause though is the lack of cost/benefit evaluation when adding new features. This pattern is apopular among FLOSS projects when it comes to wikies, not so much when it comes to issue trackers.
changed this line in version 2 of the diff
19 20 The below may seem like a lot to take in, but please don't worry about getting 21 it right the first few times. The worst that can happen is that you'll get a 22 friendly message from a current contributor who explains the process. We welcome 23 and value all contributions to the project! 24 10 25 11 26 ### Milestones 12 27 13 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). 31 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. I would rephrase this to be accurate.
- Gitlab have its foundation on agile movement. Epics are not the result of the aggregation of tasks. Epics are big user stories that require decomposition in smaller independent and demonstrable pieces of work, called on gitlab tasks. The note referring epics as a collection of tasks would be a traditional approach when it comes to work packages structure.
- The concept of sub tasks does not apply to gitlab. I would not use it.
changed this line in version 2 of the diff
14 15 - Full transparency of the current work in progress items. 16 - Provide a view of all current and planned activity which is relatively easy 17 for the viewer to digest. 18 - Ensure that we keep it simple and easy to contribute to the project. 19 20 The below may seem like a lot to take in, but please don't worry about getting 21 it right the first few times. The worst that can happen is that you'll get a 22 friendly message from a current contributor who explains the process. We welcome 23 and value all contributions to the project! 24 10 25 11 26 ### Milestones 12 27 13 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 changed this line in version 2 of the diff
49 [BuildStream project specific labels](https://gitlab.com/BuildStream/buildstream/labels). 24 50 25 Check the global scale labels: <https://gitlab.com/groups/BuildStream/-/labels> 51 When raising an issue, please consider which labels are appropriate: 26 52 27 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. 28 54 29 * Status scale: 30 * Backlog: default state on Gitlab so no label needed. 31 * Todo: processed elements that should be done in the future. 32 * Doing: WIP 33 * Review: items that are under review once the developer or contributor has finished it. 34 * Closed: items that has been processed and canceled, finished or no longer apply. Default state on Gitlab so no label needed. 35 * 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: No. Severity scale is applied by BuildStream developers, not users. This is the severity evaluation from the developers point of view, not the users. Please make this clear since we already have issues about it.
Opening the ticket and adding a bug label is the only thing the project requires open a bug.
changed this line in version 2 of the diff
52 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> 53 63 54 64 ### Issue Boards 55 65 56 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). 57 70 58 * Check the description of labels on Gitlab: <https://about.gitlab.com/features/issueboard/> 59 * Check the global boards: <https://gitlab.com/groups/BuildStream/-/boards/580444?milestone_title=BuildStream_v1.1>&= 60 * Check the buildstream repo specific boards: <https://gitlab.com/BuildStream/buildstream/boards/580451?milestone_title=BuildStream_v1.1>&= 61 * 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 changed this line in version 2 of the diff
27 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. 28 54 29 * Status scale: 30 * Backlog: default state on Gitlab so no label needed. 31 * Todo: processed elements that should be done in the future. 32 * Doing: WIP 33 * Review: items that are under review once the developer or contributor has finished it. 34 * Closed: items that has been processed and canceled, finished or no longer apply. Default state on Gitlab so no label needed. 35 * 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: 36 56 * No label: unprocessed item, no or low priority. 37 57 * Important: default severity for processed items that should be executed/considered. 38 58 * Urgent: to pay attention in the immediate future when possible. 39 59 * Critical: topics that require attention immediately when possible. 40 * Impact scale: this scale is restricted to the buildstream project for now. 44 45 Check the buildstream project specific topic labels: <https://gitlab.com/BuildStream/buildstream/labels> 46 47 Check the nosoftware repos topic labels 60 48 61 49 * communication project labels: <https://gitlab.com/BuildStream/nosoftware/communication/labels> 50 * alignment project labels: <https://gitlab.com/BuildStream/nosoftware/alignment/labels> 51 62 52 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> 53 63 54 64 ### Issue Boards 55 65 56 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 changed this line in version 2 of the diff
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. 28 54 29 * Status scale: 30 * Backlog: default state on Gitlab so no label needed. 31 * Todo: processed elements that should be done in the future. 32 * Doing: WIP 33 * Review: items that are under review once the developer or contributor has finished it. 34 * Closed: items that has been processed and canceled, finished or no longer apply. Default state on Gitlab so no label needed. 35 * 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: 36 56 * No label: unprocessed item, no or low priority. 37 57 * Important: default severity for processed items that should be executed/considered. 38 58 * Urgent: to pay attention in the immediate future when possible. 39 59 * Critical: topics that require attention immediately when possible. 40 * 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. 
I'm not sure what's happened - I did not intend to remove this info, iirc. My mistake.
But I do honestly feel like the impact / severity scale needs to be defined clearer. Does the policy that I link to above reflect the labels?
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: 36 56 * No label: unprocessed item, no or low priority. 37 57 * Important: default severity for processed items that should be executed/considered. 38 58 * Urgent: to pay attention in the immediate future when possible. 39 59 * Critical: topics that require attention immediately when possible. 40 * 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 * Topic labels: each repository has its own labels that allow to structure tickets per topic. 44 45 Check the buildstream project specific topic labels: <https://gitlab.com/BuildStream/buildstream/labels> 46 47 Check the nosoftware repos topic labels 60 48 61 49 * communication project labels: <https://gitlab.com/BuildStream/nosoftware/communication/labels> 143 144 #### Update a bug 145 146 Assuming the bulk of the work on bugs takes places on Merge Requests (code), it is strongly recommended that you follow these advices: 147 * Assign the bug to you. More than one person can be assigned to a single bug. 148 * Assign the correct milestone and labels if they are not in place already. 149 * If the bug is being investigated or resolved, please assign the label "Doing", removing the "ToDo" label. 150 * 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. 151 * Update the ticket when a relevant event takes place. In any case, update the ticket every couple of days. 152 * This is very important for others to follow up your work. 153 154 ## Merge requests: best practices. 83 [Templates](https://docs.gitlab.com/ee/user/project/description_templates.html) are a good way to prompt users for certain information. 155 84 156 These are the different policies that the project applies to merge requests. 85 When opening a new isue or merge request, please follow the template guideline, and include as much information as possible. 83 [Templates](https://docs.gitlab.com/ee/user/project/description_templates.html) are a good way to prompt users for certain information. 155 84 156 These are the different policies that the project applies to merge requests. 85 When opening a new isue or merge request, please follow the template guideline, and include as much information as possible. 157 86 158 #### Close a Bug 87 We have two templates for issues: 159 88 160 (coming soon) 89 * Bugs 90 * Tasks 161 91 162 ### Merge requests (MR): best practices 92 ### Raising a ticket (ie, gitlab issue): best practice 163 93 164 #### Open/create a merge request 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: 179 103 180 #### Update a merge request 181 182 It is strongly recommended that you follow these advices: 183 * 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. 184 * Assign the correct milestone and labels if they are not in place already. 185 * If the MR is in progress, please assign to it the label "Doing", removing the "ToDo" label if present. 186 * every MR should be related in the description field to at least one engineering task or bug. Please check this is the case. 187 * Update the MR when a relevant event takes place. 104 - self-assign the ticket 57 70 58 * Check the description of labels on Gitlab: <https://about.gitlab.com/features/issueboard/> 59 * Check the global boards: <https://gitlab.com/groups/BuildStream/-/boards/580444?milestone_title=BuildStream_v1.1>&= 60 * Check the buildstream repo specific boards: <https://gitlab.com/BuildStream/buildstream/boards/580451?milestone_title=BuildStream_v1.1>&= 61 * 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. 62 75 63 There are three main groups of boards: 76 There are two main types of boards: 64 77 65 * 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. 66 * 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. 67 * Other boards: there are other kind of boards for specific use cases. I've heard complaints recently that people did not know how to follow the policies of the project related to Gitlab. People found the policies to be difficult to consume, so this MR is an attempt to simplify them and make them more accessible.
I believe this is not really a surprise. I would never look beyond the project itself for how to interact with it. How many hits are the docs in the buildstream/nosoftware space actually getting? Is a change in the content here actually going to change anything for developers?
I believe this is not really a surprise. I would never look beyond the project itself for how to interact with it. How many hits are the docs in the buildstream/nosoftware space actually getting? Is a change in the content here actually going to change anything for developers?
Agreed.
That said, I would be happy to add the guidelines to
CONTRIBUTING.rstif they were much less complicated, overly complicated issue tracking guidelines may have a worse effect (especially for new contributors or potential fly by patch submitters) than guidelines hiding in a separate repository that nobody reads.My view here is that we tried to squeeze a kanban into our issue tracking and that the experiment proved that this is inefficient and adds too much noise to wade through in order to interact with the issue tracking side of things, as I tried to express in this mail.
Maybe it is time to revert to minimizing our usage of gitlab features in order to have a sensible and coherent policy that is manageable and welcoming to newcomers.
Just to clarify the background.... when the policy was written, there was a bottleneck on the review process. Adding the policies to a different repo was wise. There was no web, the contributing.rst was not as in the current state and the GNOME wiki was the default place we were using for contents.
The policy has not been advertised because it has been been never completed. I would only publish it section by section when it is completed.
I absolutely disagree with @tristan view on the proposal I made. I think the need for WIP visibility is underestimated and that the situation in this regard, although far from perfect, is better that what I found when I joined.
@LaurenceUrhegyi the issue where the changes in the policy has been captured are #9 and #11 If there is too much info already, we can create a new one and relate it.
Edited by toscalixI absolutely disagree with @tristan view on the proposal I made. I think the need for WIP visibility is underestimated and that the situation in this regard, although far from perfect, is better that what I found when I joined.
I think the key here is to strike a balance between what is valuable to whom.
While the visibility of details of work in progress has little or no value to the project state itself, I can see that it has value to you and @LaurenceUrhegyi as managers who are tracking the work and progress of individuals.
If this adds value for two participants at a high expense to everyone else, then you should figure out another way to track progress of work done by the individuals you oversee.
Also we should consider that this only works for contributing individuals and organizations who agree to participate in this tracking, it works for you and @LaurenceUrhegyi now, but it is inappropriate to impose this on any third parties whom would want to contribute to the project.
