github.com/oam-dev/kubevela@v1.9.11/ISSUE_TRIAGE.md (about) 1 # Triage issues 2 3 The main goal of issue triage is to categorize all incoming KubeVela issues and make sure each issue has all basic 4 information needed for anyone else to understand and be able to start working on it. 5 6 > **Note:** This information is for OAM/KubeVela project Maintainers, Owners, and Admins. 7 > If you are a Contributor, then you will not be able to perform most of the tasks in this topic. 8 9 The core maintainers of the OAM/KubeVela project are responsible for categorizing all incoming issues and delegating 10 any critical or important issue to other maintainers. Currently one maintainer each week is responsible. 11 Besides that part, triage provides an important way to contribute to an open source project. 12 13 Triage helps ensure issues resolve quickly by: 14 15 - Ensuring the issue's intent and purpose is conveyed precisely. This is necessary because it can be difficult for 16 an issue to explain how an end user experiences a problem and what actions they took. 17 - Giving a contributor the information they need before they commit to resolving an issue. 18 - Lowering the issue count by preventing duplicate issues. 19 - Streamlining the development process by preventing duplicate discussions. 20 21 If you don't have the knowledge or time to code, consider helping with triage. 22 The community will thank you for saving them time by spending some of yours. 23 24 ## Simplified flowchart diagram of the issue triage process 25 26 <!-- https://textik.com/#908a27a44c590528 --> 27 ``` 28 +-----------------------------+ 29 | | 30 | New Issues Opened | 31 +-----------------+ | 32 | | Or More information needed | 33 | | | 34 | +--------------+--------------+ 35 | Ask for more info | 36 | | 37 | +--------------+------------+ 38 | | | Yes 39 | | All informatio needed | 40 | +-----------+ to categorize the issue？ +---------------+ 41 | | No | | | 42 | | +---------------------------+ | 43 | | +-----------+-----------+ +---------------------------+ 44 +------------+-----+-----+ | | Yes | | 45 | | | Needs investigation ？ +---------+ label: needs investigation| 46 | label: needs more info | | | | | 47 | | +----------+------------+ +-------------+-------------+ 48 +------------------------+ | | 49 | No | 50 | | 51 +----------+----------+ investigate | 52 | label: type/* | | 53 | label: area/* +--------------------------+ 54 | | 55 +--|-------------|----+ 56 | | Yes 57 | +-------|-------------+ +-------------------+ 58 | | needs priority？ +----+ label: priority/* | 59 | +-------|-------------+ +----------|--------+ 60 | | No | 61 | | | 62 +----- ------|---+ +--|----- --+ | 63 | close issue + ---- + done +---------------------+ 64 +----------------+ +-----------+ 65 ``` 66 67 ## 1. Find uncategorized issues 68 69 To get started with issue triage and finding issues that haven't been triaged you have two alternatives. 70 71 ### Browse unlabeled issues 72 73 The easiest and straight forward way of getting started and finding issues that haven't been triaged is to browse 74 [unlabeled issues](https://github.com/kubevela/kubevela/issues?q=is%3Aopen+is%3Aissue+no%3Alabel) and starting from 75 the bottom and working yourself to the top. 76 77 ### Subscribe to all notifications 78 79 The more advanced, but recommended way is to subscribe to all notifications from this repository which means that 80 all new issues, pull requests, comments and important status changes are sent to your configured email address. 81 Read this [guide](https://help.github.com/en/articles/watching-and-unwatching-repositories#watching-a-single-repository) 82 for help with setting this up. 83 84 It's highly recommended that you setup filters to automatically remove emails from the inbox and label/categorize 85 them accordingly to make it easy for you to understand when you need to act upon a notification or where to look for 86 finding issues that haven't been triaged etc. 87 88 89 ## 2. Ensure the issue contains basic information 90 91 Before triaging an issue very far, make sure that the issue's author provided the standard issue information. 92 This will help you make an educated recommendation on how to categorize the issue. 93 The KubeVela project utilizes [GitHub issue templates](https://help.github.com/en/articles/creating-issue-templates-for-your-repository) 94 to guide contributors to provide standard information that must be included for each type of template or type of issue. 95 96 ### Standard issue information that must be included 97 98 Given a certain [issue template]([template](https://github.com/kubevela/kubevela/issues/new/choose)) have been used 99 by the issue author or depending how the issue is perceived by the issue triage responsible, the following should 100 help you understand what standard issue information that must be included. 101 102 #### Bug reports 103 104 Should explain what happened, what was expected and how to reproduce it together with any additional information that 105 may help giving a complete picture of what happened such as screenshots, application related YAMLs, and any environment 106 related information that's applicable and/or maybe related to the reported problem: 107 - KubeVela version 108 - K8s cluster version KubeVela is installed on 109 - Which other K8s CRD controllers used 110 - Development environment like Go versions, if applicable 111 112 #### Enhancement requests 113 114 Should explain what enhancement or feature that the author wants to be added and why that is needed. 115 116 ### Good practices 117 118 To make it easier for everyone to understand and find issues they're searching for it's suggested as a general rule of thumbs to: 119 120 - Make sure that issue titles are named to explain the subject of the issue, has a correct spelling and doesn't include irrelevant information and/or sensitive information. 121 - Make sure that issue descriptions doesn't include irrelevant information, information from template that haven't been filled out and/or sensitive information. 122 - Do your best effort to change title and description or request suggested changes by adding a comment. 123 124 > **Note:** Above rules is applicable to both new and existing issues of the KubeVela project. 125 126 ### Do you have all the information needed to categorize an issue? 127 128 Depending on the issue, you might not feel all this information is needed. Use your best judgement. 129 If you cannot triage an issue using what its author provided, explain kindly to the author that they must provide the 130 above information to clarify the problem. Label issue with `needs more info` and add any related `area/*` or `type/*` labels. 131 132 If the author provides the standard information but you are still unable to triage the issue, request additional information. 133 Do this kindly and politely because you are asking for more of the author's time. 134 135 If the author does not respond to the requested information within the timespan of a week, 136 close the issue with a kind note stating that the author can request for the issue to be reopened when the necessary information is provided. 137 138 When you feel you have all the information needed you're ready to [categorizing the issue](#3-categorizing-an-issue). 139 140 If you receive a notification with additional information provided but you are not anymore on issue triage and 141 you feel you do not have time to handle it, you should delegate it to the current person on issue triage. 142 143 ## 3. Categorizing an issue 144 145 An issue can have multiple of the following labels. Typically, a properly categorized issue should at least have: 146 147 - One label identifying its type (`type/*`). 148 - One or multiple labels identifying the functional areas of interest or component (`area/*`), if applicable. 149 150 | Label | Description | 151 | ------------------------ | ------------------------------------------------------------------------- | 152 | `type/bug` | A feature isn't working as expected given design or documentation. | 153 | `type/enhancement` | Request for a new feature or enhancement. | 154 | `type/docs` | Documentation problem or enhancement. | 155 | `type/question` | Issue is a question or is perceived as such. | 156 | `type/duplicate` | An existing issue of the same subject/request have already been reported. | 157 | `type/wontfix` | A reported bug works as intended/by design. | 158 | `type/invalid` | A reported bug with invalid usage. | 159 | `area/*` | Subject is related to a functional area of interest or component. | 160 161 ### Duplicate issues 162 163 Make sure it's not a duplicate by searching existing issues using related terms from the issue title and description. 164 If you think you know there is an existing issue, but can't find it, please reach out to one of the maintainers and ask for help. 165 If you identify that the issue is a duplicate of an existing issue: 166 167 1. Add a comment `/duplicate of #<issue number>`. GitHub will recognize this and add some additional context to the issue activity. 168 2. The KubeVela bot will do the rest, adding the correct label and closing comment 169 3. Optionally add any related `area/*` labels. 170 171 ### Bug reports 172 173 If it's not perfectly clear that it's an actual bug, quickly try to reproduce it. 174 175 **It's a bug/it can be reproduced:** 176 177 1. Add a comment describing detailed steps for how to reproduce it, if applicable. 178 2. Label the issue `type/bug` and at least one `area/*` label. 179 3. If you know that maintainers won't be able to put any resources into it for some time then label the issue 180 with `help wanted` and optionally `good first issue` together with pointers on which code to update to fix the bug. 181 This should signal to the community that we would appreciate any help we can get to resolve this. 182 4. Move on to [prioritizing the issue](#4-prioritization-of-issues). 183 184 **It can't be reproduced:** 185 1. Either [ask for more information](#2-ensure-the-issue-contains-basic-information) needed to investigate it more thoroughly. 186 2. Either [delegate further investigations](#investigation-of-issues) to someone else. 187 188 **It works as intended/by design:** 189 1. Kindly and politely add a comment explaining briefly why we think it works as intended and close the issue. 190 2. Label the issue `type/wontfix`. 191 192 ### Enhancement/feature? 193 194 1. Label the issue `type/enhancement` and at least one `area/*` label. 195 2. Move on to [prioritizing the issue](#4-prioritization-of-issues). 196 197 ### Documentation issue? 198 199 First, evaluate if the documentation makes sense to be included in the KubeVela project: 200 201 - Is this something we want/can maintain as a project? 202 - Is this referring to usage of some specific integration/tool and in that case is that a popular use case in combination with KubeVela? 203 - If unsure, kindly and politely add a comment explaining that we would need [upvotes](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments) 204 to identify that lots of other users want/need this. 205 206 Second, label the issue `type/docs` and at least one `area/*` label. 207 208 **Minor typo/error/lack of information:** 209 210 There's a minor typo/error/lack of information that adds a lot of confusion for users and given the amount of work is a big win to make sure fixing it: 211 1. Either update the documentation yourself and open a pull request. 212 2. Either delegate the work to someone else by assigning that person to the issue and add the issue to next major/minor milestone. 213 214 **Major error/lack of information:** 215 216 1. Label the issue with `help wanted` and `good first issue`, if applicable, to signal that we find this important to 217 fix and we would appreciate any help we can get from the community. 218 2. Move on to [prioritizing the issue](#4-prioritization-of-issues). 219 220 ### Support requests and questions 221 222 1. Kindly and politely direct the issue author to the [github discussion](https://github.com/kubevela/kubevela/discussions) 223 and explain that issue is mainly used for tracking bugs and feature requests. 224 If possible, it's usually a good idea to add some pointers to the issue author's question. 225 2. Close the issue and label it with `type/question`. 226 227 ## 4. Prioritization of issues 228 229 In general bugs and enhancement issues should be labeled with a priority. 230 231 This is the most difficult thing with triaging issues since it requires a lot of knowledge, context and experience 232 before being able to think of and start feel comfortable adding a certain priority label. 233 234 The key here is asking for help and discuss issues to understand how more experienced project members think and reason. 235 By doing that you learn more and eventually be more and more comfortable with prioritizing issues. 236 237 In case there is an uncertainty around the prioritization of an issue, please ask the maintainers for help. 238 239 | Label | Description | 240 | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | 241 | `priority/critical` | Highest priority. Must be actively worked on as someone's top priority right now. | 242 | `priority/important-soon` | Must be staffed and worked on either currently, or very soon, ideally in time for the next release. | 243 | `priority/important-longterm` | Important over the long term, but may not be staffed and/or may need multiple releases to complete. | 244 | `priority/nice-to-have` | It's a good idea, but not scheduled for any release. | 245 | `priority/awaiting-more-evidence` | Lowest priority. Possibly useful, but not yet enough interest in it. | 246 | `priority/unscheduled` | Something to look into before and to be discussed during the planning of the next (upcoming) major/minor stable release. | 247 248 **Critical bugs** 249 250 1. If a bug has been categorized and any of the following criteria apply, the bug should be labeled as critical and 251 must be actively worked on as someone's top priority right now. 252 253 - Results in any crash or data loss. 254 - Critical security or performance issues 255 - Problem that makes a feature unusable 256 - Multiple users experience a severe problem affecting their business, users etc. 257 258 2. Label the issue `priority/critical`. 259 3. Add the issue to the next upcoming patch release milestone. Create a new milestone if there are none. 260 4. Escalate the problem to the maintainers. 261 5. Assign or ask a maintainer for help assigning someone to make this issue their top priority right now. 262 263 **Important short-term** 264 265 1. Label the issue `priority/important-soon`. 266 2. Add the issue to the next upcoming patch or major/minor stable release milestone. Ask maintainers for help if unsure if it's a patch or not. 267 Create a new milestone if there are none. 268 3. Make sure to add the issue to a suitable backlog of a GitHub project and prioritize it or assign someone to work on it now or very soon. 269 4. Consider requesting [help from the community](#5-requesting-help-from-the-community), even though it may be problematic given a short amount of time until it should be released. 270 271 **Important long-term** 272 273 1. Label the issue `priority/important-longterm`. 274 2. Consider requesting [help from the community](#5-requesting-help-from-the-community). 275 276 **Nice to have** 277 278 1. Label the issue `priority/nice-to-have`. 279 2. Consider requesting [help from the community](#5-requesting-help-from-the-community). 280 281 **Not critical, but unsure?** 282 283 1. Label the issue `priority/unscheduled`. 284 2. Consider requesting [help from the community](#5-requesting-help-from-the-community). 285 286 ## 5. Requesting help from the community 287 288 Depending on the issue and/or priority, it's always a good idea to consider signalling to the community that help from community 289 is appreciated and needed in case an issue is not prioritized to be worked on by maintainers. Use your best judgement. 290 In general, requesting help from the community means that a contribution has a good chance of getting accepted and merged. 291 292 1. Kindly and politely add a comment to signal to users subscribed to updates of the issue. 293 - Explain that the issue would be nice to get resolved, but it isn't prioritized to work on by maintainers for an unforeseen future. 294 - If possible or applicable, try to help contributors getting starting by adding pointers and references to 295 what code/files need to be changed and/or ideas of a good way to solve/implement the issue. 296 2. Label the issue with `help wanted`. 297 3. If applicable, label the issue with `good first issue` to denote that the issue is suitable for a beginner to work on. 298 4. If possible, try to estimate the amount of work by adding `effort/small`, `effort/medium` or `effort/large`. 299 300 ## Investigation of issues 301 302 When an issue has all basic information provided, but the triage responsible haven't been able to reproduce the reported 303 problem at a first glance, the issue is labeled [Needs investigation](https://github.com/oam-dev/kubevela/labels/needs%20investigation). 304 Depending on the perceived severity and/or number of [upvotes](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments), 305 the investigation will either be delegated to another maintainer for further investigation or put on hold until someone else (maintainer or contributor) 306 picks it up and eventually starts investigating it. 307 308 Investigating issues can be a very time consuming task, especially for the maintainers, provide as much related info will 309 make it easier for maintainers to investigate. 310 311 Even if you don't have the time or knowledge to investigate an issue we highly recommend that you [upvote](https://help.github.com/en/articles/about-conversations-on-github#reacting-to-ideas-in-comments) 312 the issue if you happen to have the same problem. If you have further details that may help investigating the issue 313 please provide as much information as possible. 314 315 ## Automation 316 317 We have some automation that triggers on comments or labels being added to issues. 318 Many of these automated behaviors are defined in [issue-commands.json](https://github.com/oam-dev/kubevela/blob/master/.github/issue-commands.json). 319 320 * Add comment `/duplicate #<number>` to have `type/duplicate` label, the issue number is required for remind where is the other issue. 321 * Add label `bot/no new info` for bot to close an issue where we asked for more info but has not received any updates in at least 14 days. 322 323 Read more bot actions on [bot.md](https://github.com/oam-dev/kubevela/blob/master/.github/bot.md)