Create Issue Triage Guideline #787

spzala · 2017-07-06T22:01:26Z

This guideline was initially created and proposed by Sahdev Zala and
Jorge Castro. It has been discussed multiple times in the ContribX
SIG meetings and via emails, and it incorporates all the suggestions. This
PR is created per the latest SIG meeting discussion.
The original open document with little bit more content is available here,
https://docs.google.com/document/d/1dfZGGIsx4QrY8aaC1o2SNmMU6eQKS4xYg55xNLtHDmc/edit

Co-Authored-By: Jorge Castro jorge@heptio.com

spzala · 2017-07-06T22:01:50Z

/cc @castrojo

cblecker · 2017-07-06T22:43:04Z

contributors/triage/README.md

+This directory contains Kubernetes Issue Triage Guideline and related documents.
+
+Triaging issues is a great way to get started contributing, and it will help you understand how the project is organized. Here’s a few predetermined searches for convenience:  
+* [Longest Untriaged issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)) (sorted by age)


nit: extra bracket

cblecker · 2017-07-06T22:43:12Z

contributors/triage/README.md

+* [Longest Untriaged issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)) (sorted by age)
+* [Needs to be assigned to a SIG](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)
+* [Newest incoming issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue)
+* Busy Untriaged issues (sorted by number of comments, then by age) 


is this supposed to be a link?

@cblecker yes ideally but is there a way to combine two 'sort' conditions (something like is:open is:issue sort:comments-desc and is:open is:issue sort:created-asc) /cc @castrojo ?

I don't think there's a way to do two sorting conditions, I guess we can just drop this for now until we figure out something more clever?

@castrojo Thanks Jorge!! Other thought, in that case, let's just keep it to 'sorted by number of comments'.

cblecker · 2017-07-06T22:45:44Z

contributors/triage/guideline.md

+* If you do not get response in 15 days, then close the issue with appropriate comment.
+
+## Find the right SIG(s)
+Components are divided among[ Special Interest Groups (SIGs)](https://github.com/kubernetes/community/blob/master/sig-list.md). Find a proper SIG for the ownership of the issue using the bot:


nit: space and left square bracket should be reversed

cblecker · 2017-07-06T22:49:06Z

contributors/triage/guideline.md

+
+## Set ownership
+
+All issues should have an owner, if you are not sure of an owner, then the SIG should assign one later down the line. You can ping a team with an @ mention, like `@sig-cluster-lifecycle, can you have a look at this?` if you feel the issue should warrant a notification.


nit: mentions need @kubernetes/ before the sig part

Thanks @cblecker I had no idea :). Did you mean @kubernetes/sig-cluster-lifecycle ? or @k8s-@kubernetes/sig-cluster-lifecycle ? I am also seeing @k8s-sig-x.

@kubernetes/sig-cluster-lifecycle-pr-reviews for example (putting it in back ticks so it doesn't actually mention)

Thanks @cblecker !! To educate myself, shouldn't it auto fill when I use it in the issue? (e.g. shouldn't use of @kubernetes/sig- auto fill?) /cc @castrojo

You need to be an org member to directly mention people. To get around that, the bot will echo any mentions from non-org members

Like, for example, try mentioning @kubernetes/sig-contributor-experience-misc (who can be mentioned on this PR anyways)

@cblecker cool 👍 Thanks!!

cblecker · 2017-07-06T22:52:32Z

contributors/triage/guideline.md

+
+## Define priority
+After you validate the issue, optionally, per your understanding add a comment of what you think of priority of fixing issue - critical, high, medium, low, wishlist. This doesn’t required to be accurate. The owner from appropriate SIG will assign a correct priority. 
+* `priority/failing-test or priority/critical-urgent` (P0 - Critical - fix it now, it’s a blocker)


nit: perhaps take the or outside of the backticks
e.g.: priority/failing-test or priority/critical-urgent

spzala · 2017-07-06T23:54:35Z

@kubernetes/sig-contributor-experience-misc

@cblecker like above? it didn't auto fill... I guess I am missing something :(

cblecker · 2017-07-07T00:03:16Z

Boo.. looks like there's an issue for it: kubernetes/test-infra#2956

spzala · 2017-07-07T00:06:52Z

Ahhh.. :-) OK, so that's fine, for the guildeline I will add it as you suggested.

castrojo

LGTM other than the formatting issues cblecker has mentioned.

spzala · 2017-07-07T14:24:09Z

@castrojo Thanks!

cmluciano · 2017-07-07T16:18:41Z

contributors/triage/README.md

@@ -0,0 +1,13 @@
+# Kubernetes Issue Triage
+
+This directory contains Kubernetes Issue Triage Guideline and related documents.


s/Guideline/Guidelines

@cmluciano sure, I will update accordinlyg everywhere in the doc.

cmluciano · 2017-07-07T16:19:10Z

contributors/triage/README.md

+
+This directory contains Kubernetes Issue Triage Guideline and related documents.
+
+Triaging issues is a great way to get started contributing, and it will help you understand how the project is organized. Here’s a few predetermined searches for convenience:  


s/Here's/Here are

@cmluciano How about "Following are few .. " ?

You could just say "Useful queries:"

:-) OK that's good too but let's just leave as such with use of 'are'..I believe you are OK either way. Thanks!

cmluciano · 2017-07-07T16:20:13Z

contributors/triage/README.md

+* [Newest incoming issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue)
+* [Busy Untriaged issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) (sorted by number of comments)
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->


Is this something generated by the build scripts?

@cmluciano Nope..and so I guess I should remove the commented lines for GENERATED_ANALYITICS in both the files? I am seeing these lines at the bottom of all doc files (unless I missed), thought they are to generate some sort of usage analytics. Thanks!

https://github.com/kubernetes/community/blob/master/contributors/devel/how-to-doc.md

cmluciano · 2017-07-07T16:21:20Z

contributors/triage/guideline.md

+
+Speed up issue management.
+
+The Kubernetes issues are listed at https://github.com/kubernetes/kubernetes/issues. The issues are identified with labels. For example, an issue that belongs to SIG Network will eventually be set to label `sig/network`. New issues will start out without any labels. The detailed list of labels can be found at https://github.com/kubernetes/kubernetes/labels. While working on triaging issues you may not have privilege to assign specific label (e.g. `triaged`) and in that case simply add a comment in the issue with your findings.


Nit:

Combine first two sentences:

The Kubernetes issues are listed at https://github.com/kubernetes/kubernetes/issues and are identified with labels.

cmluciano · 2017-07-07T16:22:56Z

contributors/triage/guideline.md

+
+## Using the bot
+
+Most people do not have the ability to interact with the github issues and labels, for that we use a bot to manage labelling and triaging. The bot has a set of [commands and permissions](https://github.com/kubernetes/test-infra/blob/master/commands.md), this document will cover the basic ones. 


and this document...

cmluciano · 2017-07-07T16:27:31Z

contributors/triage/guideline.md

+* Do a quick duplicate search to see if the issue has been reported already. If duplicate, let the issue reporter know it by marking it duplicate.
+* If you can not reproduce the issue, contact issue reporter with your findings and close the issue if both the parties agree that it could not be reproduced.
+* If the issue is non-trivial to reproduce work with issue reporter or move to next step of finding a right SIG, and let SIG know of your findings.
+* If you do not get response in 15 days, then close the issue with appropriate comment.


cmluciano · 2017-07-07T16:28:19Z

contributors/triage/guideline.md

+* Multiword SIGs use dashes, for example `/sig cluster-lifecycle`.
+
+## Define priority
+After you validate the issue, optionally, per your understanding add a comment of what you think of priority of fixing issue - critical, high, medium, low, wishlist. This doesn’t required to be accurate. The owner from appropriate SIG will assign a correct priority. 


Can probably remove "optionally, per your understanding"

"This doesn't sentence"

I'm not sure what this sentence is saying

I don't see "This doesn't sentence" :( I am modifying it as "After you validate the issue, add a comment of what you think of priority of fixing issue - critical, high, medium, low, wishlist. This step is not mandatory and assigning priority doesn’t required to be accurate. The owner from appropriate SIG will assign a correct priority." - does that look good?

I meant to say "This doesn't required to be accurate" does not make sense.

I think we can delete this sentence

Sure, fine with me.

cmluciano · 2017-07-07T16:29:51Z

contributors/triage/guideline.md

+* `priority/important-soon` or `priority/important-longterm`  (P1 - High - functional error requiring quick fix)
+* `priority/backlog`  (P2 - Medium - error but not critical, small issue, for example, typo)
+* `priority/awaiting-more-evidence` (P3 - Low)
+* (P4 - Wishlist - not a real bug but suggestion or new feature request)


How is wishlist different from backlog?

To me, backlog is 'should be fixed as soon as possible' and wishlist is 'fix if you can' .. though wishlist can be potentially a part of overall backlog.

I always viewed backlog as "we want to do this, but we have not targeted it for a milestone yet"

Perhaps others from @kubernetes-pm can weigh in

If there is no corresponding label I would get rid of this P4 bullet point entirely. The priority/awaiting-more-evidence label sounds pretty wishlist-esque to me, a-la "it sounds like a great idea but we're awaiting more evidence that it's actually worth doing or that someone has expressed an interest in tackling it"

@spiffxp makes sense, I am removing the P4 bullet. Thanks!

wishlist == awaiting-more-evidence

If we'd never, ever do it, just close.

Also, "fixes" of low-priority issues have non-trivial costs (reviews, babysitting, submit queue bandwidth, etc.), so if they really are very low priority, we shouldn't encourage anyone to work on them.

cmluciano · 2017-07-07T16:31:18Z

contributors/triage/guideline.md

+
+## Set ownership
+
+All issues should have an owner, if you are not sure of an owner, then the SIG should assign one later down the line. You can ping a team with an @ mention, like `@kubernetes/sig-cluster-lifecycle, can you have a look at this?` if you feel the issue should warrant a notification.


All issues should have an owner. If you are unsure of the ownership, defer to the SIG label only.

cmluciano · 2017-07-07T16:32:29Z

contributors/triage/guideline.md

+
+If you think you can fix the issue, assign it to yourself with just `/assign`.
+
+## Poke issue owner if PR is not created for it in 30 days


Do priority labels play a role in this timeline?

Good question. I am open for discussion but I think regardless of priority we can keep a fix number here for simplicity. The owner should add a comment to indicate that what's the expected time frame in any case.

xiangpengzhao · 2017-07-16T04:56:17Z

contributors/triage/README.md

+* [Needs to be assigned to a SIG](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc)
+* [Newest incoming issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue)
+* [Busy Untriaged issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) (sorted by number of comments)
+


I'd like to have a Least commented issues. Few comments sometimes means less concern. They need more love.

@xiangpengzhao these queries are just few examples but sure I will add one as you suggested.

xiangpengzhao · 2017-07-16T05:05:43Z

contributors/triage/guideline.md

+
+## Determine if it’s a support request
+
+Sometimes users ask for support requests in issues; these are usually support requests for people who need help configuring some aspect of Kubernetes. These should be directed to our [support structures](https://github.com/kubernetes/community/blob/master/contributors/devel/on-call-user-support.md) and then closed. Only authors and assignees can `/close` an issue. Also, if the issue is clearly abandoned or in the wrong place you can `/assign` to have it assigned to yourself, and then `/close`.


Also, if the issue is clearly abandoned or in the wrong place you can /assign to have it assigned to yourself, and then /close.

Only org members can self-assign issues which they're not authors of.

@xiangpengzhao true, and in the beginning of this guide we have mentioned it that not everyone have privilege to assign or close :) but if it's unclear I will briefly mention it here too.

Hmm, I missed that:)

@xiangpengzhao :) np and your suggestion is still valid. It's good to be clear by briefly re-mention.

xiangpengzhao · 2017-07-16T05:08:10Z

contributors/triage/guideline.md

+* Do a quick duplicate search to see if the issue has been reported already. If a duplicate is found, let the issue reporter know it by marking it duplicate.
+* If you can not reproduce the issue, contact the issue reporter with your findings and close the issue if both the parties agree that it could not be reproduced.
+* If the issue is non-trivial to reproduce, work with issue reporter or move to next step of finding a right SIG, and let SIG know of your findings.
+* If you do not get a response in 15 days, then close the issue with appropriate comment.


15 days seem like short when guys are in busy days.

@xiangpengzhao true but it can always be reopened so I prefer it :). We had some discussion and we came up with little aggressive dead line. I would bring it up in Contrib SIG meeting or we can discuss it here if you want. /cc @castrojo

Yeah it can be reopened but I don't think guys (except the issue reporters, maybe) will pay enough attention to closed issues. Most people may think closed issues are resolved.

True, but yeah, my hope is issue reporter will pay attention to the comment, that issue was closed w/o resolving because of such an such reason, and will reopen with more information. But I am open for any suggestion. I am increasing to 20 days for now.

15 days is way too short. Also, this kind of policy only makes sense for bug reports.

And without a process to go over bug reports and assess severity/priority, many bugs would just be closed, so we need to recommend such a process.

xiangpengzhao · 2017-07-16T05:14:18Z

contributors/triage/guideline.md

+
+All issues should have an owner. If you are not sure of an owner, defer to the SIG label only. You can ping a team with an @ mention, like `@kubernetes/sig-cluster-lifecycle, can you have a look at this?` if you feel the issue should warrant a notification.
+
+If you think you can fix the issue, assign it to yourself with just `/assign`.


See my first comment please. Only org members can self-assign issues which they're not authors of.

OK, I will make it more clear.

It would be great:)

@xiangpengzhao can a org member assign issue to non-org member/developer? I believe so, and if so, I will make updates accordingly. Thanks!

Unfortunately, no. This is a good example: kubernetes/kubernetes#47010

Hah, that's unfortunate :(

xiangpengzhao · 2017-07-16T05:18:04Z

contributors/triage/guideline.md

+
+## Set ownership
+
+All issues should have an owner. If you are not sure of an owner, defer to the SIG label only. You can ping a team with an @ mention, like `@kubernetes/sig-cluster-lifecycle, can you have a look at this?` if you feel the issue should warrant a notification.


This way to mention will not work. See the right example: kubernetes/kubernetes#48990 (comment)

/cc @crimsonfaith91

@xiangpengzhao OK, that's good point. So the example here, for a bug, should be "@kubernetes/sig-cluster-lifecycle-bugs" - does that sounds correct? @castrojo - we should then add a line or two in the guideline about what a group suffix should be (i.e. one of the "bugs, feature-requests, pr-reviews, test-failures, proposals")? Thanks!

Yeah, correct.

cool, thanks @xiangpengzhao

The teams are documented here:

https://github.com/kubernetes/community/blob/master/sig-governance.md#create-the-github-teams

The purpose could be documented better.

Please avoid using the *-misc teams as much as possible.

spiffxp · 2017-07-17T21:57:36Z

contributors/triage/guideline.md

+
+## Define priority
+After you validate the issue, add a comment of what you think of priority of fixing issue - critical, high, medium, low, wishlist. The owner from appropriate SIG will assign a correct priority.
+* `priority/failing-test` or `priority/critical-urgent` (P0 - Critical - fix it now, it’s a blocker)


I would prefer to see the "PN" descriptions removed entirely, they're a bit misleading and don't necessarily line up with the wording of the labels. I would split each of these priority labels into their own bullet points. I don't know precisely what these labels should mean, so here's a guess:

priority/critical-urgent: this is likely a blocker... both critical (high impact) and urgent (must be done as soon as possible)

priority/failing-test: a test is failing, this is very important as too many of these impact our velocity; the immediacy of these depends on whether they block PR's, releases, or general CI signal

priority/important-soon: this is important, and we want to get it done soon (preferably this release cycle)

priority/important-longterm: this is important, but doesn't need to be or cannot be done right now, so instead we'd like to get to it later (preferably next release cycle, or once unblocked)

priority/backlog: we'd like to get to this but are unsure when (maybe two release cycles from now)

priority/awaiting-more-evidence: this is a good idea but we're awaiting more evidence that this is worth doing

FYI: https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#priorities

So I will be adding something like this - not giving detail of priorities but just brief and provide link for more detail.

priority/failing-test or priority/critical-urgent - Critical. Fix it now.

priority/important-soon or priority/important-longterm - High priority. Fix as soon as possible.

priority/backlog - Medium priority.

priority/awaiting-more-evidence - Low priority.

To read priorities in detail, please refer to the Priorities

Hope makes sense. Thanks!

I'm not sure whether the priority/important-longterm issues should be fixed ASAP. I guess no.

@xiangpengzhao yeah, thought so, but the same time thought let me keep them together but going to list them separately.

Changing to,

priority/important-soon - High priority. Fix it as soon as possible.

priority/important-longterm - High priority over the long duration.

Yes, the intent is to eliminate all numerical priorities.

spiffxp · 2017-07-17T21:58:54Z

contributors/triage/guideline.md

+
+Most people do not have the ability to interact with the github issues and labels, for that we use a bot to manage labelling and triaging. The bot has a set of [commands and permissions](https://github.com/kubernetes/test-infra/blob/master/commands.md) and this document will cover the basic ones.
+
+


spiffxp · 2017-07-17T22:04:27Z

contributors/triage/guideline.md

+* If the issue is non-trivial to reproduce, work with issue reporter or move to next step of finding a right SIG, and let SIG know of your findings.
+* If you do not get a response in 15 days, then close the issue with appropriate comment.
+
+## Find the right SIG(s)


I would put this above "validate if the issue is real"

@spiffxp sure, the 'validate..' step has instruction "to move to finding SIG..if the issue is real" but you are right, I believe regardless issue is real or not, one should first find the SIG as SIG should know of the findings in either case. So sounds good to me - moving it and modifying the "validate if the issue is real" step accordingly. Thanks!

bgrant0607 · 2017-07-18T00:28:40Z

cc @kubernetes/sig-contributor-experience-proposals

bgrant0607 · 2017-07-18T00:29:09Z

cc @jagosan

bgrant0607 · 2017-07-18T00:36:05Z

contributors/triage/README.md

@@ -0,0 +1,13 @@
+# Kubernetes Issue Triage


This appears to only be about the kubernetes/kubernetes repo?

@bgrant0607 ideally this should be for all repos i.e. kubernetes/kubernetes and related kubernetes repos. So how about I add a line in the content to make it clear? I guess we can leave title as such. Thanks!

The kubernetes repo is special, because it spans most/all SIGs and has very high issue volume. Smaller, more-focused repos don't have the same challenges. And, issue labels and bot automation don't yet apply to all repos, since they have to be set up for each repo individually.

@bgrant0607 hi Brian, agree but lot of content besides labels can be used as a guidelines for other repos. I can try adding a note with some of the text from your comment and we can keep the scope of guidelines more than just kubernetes repo? As you mentioned other repos don't have a real problem of issue management because of low volume of issues, but I heard about some more code splitting, for example, new repos like kubernetes/kubectl are under progress and I guess such repos will be similar to kubernetes/kubernetes repo. Thanks!

Multiple repos: kubernetes/kubernetes#24343

It will take quite a while to be completed.

I'm fine with a statement at the beginning stating that this only applies to the kubernetes repo and other repos are TBD.

@bgrant0607 sounds good, thanks!

bgrant0607 · 2017-07-18T02:42:06Z

contributors/triage/README.md

+* [Newest incoming issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aopen+is%3Aissue)
+* [Busy Untriaged issues](https://github.com/kubernetes/kubernetes/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) (sorted by number of comments)
+
+<!-- BEGIN MUNGE: GENERATED_ANALYTICS -->


https://github.com/kubernetes/community/blob/master/contributors/devel/how-to-doc.md

bgrant0607 · 2017-07-18T02:43:43Z

contributors/triage/README.md

@@ -0,0 +1,13 @@
+# Kubernetes Issue Triage


These kinds of docs belong in contributors/devel.

Also, the subdirectory would be more discoverable if called issues rather than triage.

And we'd ideally unify these docs with https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md

and link from
https://github.com/kubernetes/community/blob/master/contributors/devel/README.md

FWIW, the preliminary proposal was:

Design and implement sustainable issue routing (to appropriate SIG and kind [bug, feature request, etc.]). Require org members to provide this information (close if not). Round-robin assign to triage team if not provided by non-member.

https://github.com/orgs/kubernetes/projects/1#card-2296048

@bgrant0607 that's a good point to put the content under contributors/devel. Jorge and I thought about it, but we also thought let's keep Triage on it's own directory in case we are adding more specific content in future and keep it separate from pure devel docs. The issue.md is mentioned in the guidelines as a reference to learn about priorities in detail but if you think it's better to modify issues.md as guidelines that's fine with me. If contributors/devel seems better and right place, I will move the guideline there. And btw, I couldn't open the #card-2296048 link you have provided above. Thanks!

I like the round-robin for triage. Do we imagine an addition to the OWNERS files to specify a few people to triage per SIG?

It should go under contributors/devel. That's the place we direct contributors from CONTRIBUTING.md files, where the index is, etc. Also, triage is a bad name.

Sadly, org-level projects can't be made world-readable. We have an open issue to stop using them. The contents of the link was included in my previous comment.

The most important problem to solve is scaling the effort. We used to have someone assigned to triaging incoming issues and it was not possible to keep up. We need to round-robin 1st-level triage and push 2nd-level triage to SIGs. That doesn't entirely solve the problem, since the overwhelming majority of issues go to ~6 SIGs (Node, API machinery, CLI, Networking, Storage, Apps). We may need to round-robin again within those SIGs. Just saying "somebody should triage open issues" isn't going to work.

The people who triage also need some guidance. We have previously had the problem that a significant number of issues were miscategorized. No matter what we do, I'm sure some number will get re-categorized, but keeping that number small will help issues be properly triaged in a timely manner.

Additionally, it doesn't have to be in scope for this document, but some incentive will need to be put in place to induce contributors to work on bugs as opposed to features.

Regarding 1st level triage. We're doing well. Consider that there were 300+ issues opened in July 2017 and only 28 of them lack a sig label. The automation and prompting is working at driving the issues to sigs.

This does not address the miscategorization problem, nor does it address the 2nd level triage. But it's worth noting that we are getting people to apply sig labels.

bgrant0607 · 2017-07-18T02:57:43Z

contributors/triage/guideline.md

+## Purpose
+
+Speed up issue management.
+


When the lines become arbitrarily long, one can only comment on whole paragraphs, as opposed to individual lines.

Agree but sorry I didn't get your comment/suggestion here, can you please elaborate? Thanks!

For an example, look at line 19 of this file via the github UI.

@spzala this has to do with the formatting of this doc. Can you use textwrap at 80 chars or something like that so long lines are broken up. That way we can comment, give feedback with more granularity.

@grodrigues3 yup, absolutely. Thanks!!

bgrant0607 · 2017-07-18T03:04:28Z

contributors/triage/guideline.md

+
+Speed up issue management.
+
+The Kubernetes issues are listed at https://github.com/kubernetes/kubernetes/issues and are identified with labels. For example, an issue that belongs to SIG Network will eventually be set to label `sig/network`. New issues will start out without any labels. The detailed list of labels can be found at https://github.com/kubernetes/kubernetes/labels. While working on triaging issues you may not have privilege to assign specific label (e.g. `triaged`) and in that case simply add a comment in the issue with your findings.


@grodrigues3

Is labels.yaml documented anywhere?

https://github.com/kubernetes/test-infra/blob/6f7432c18267d6e9bfd6732d30e2ea4725326a99/mungegithub/mungers/check-labels.go#L42

Do we translate area labels to sig labels yet?

We should probably delete the triaged label. It was part of experiment to estimate how long it took to triage issues.

As mentioned elsewhere, bot commands should enable most people, if not everyone, to assign sig and area labels.

bgrant0607 · 2017-07-18T03:23:06Z

contributors/triage/guideline.md

+
+## Determine if it’s a support request
+
+Sometimes users ask for support requests in issues; these are usually support requests for people who need help configuring some aspect of Kubernetes. These should be directed to our [support structures](https://github.com/kubernetes/community/blob/master/contributors/devel/on-call-user-support.md) and then closed. Only authors and assignees can `/close` an issue. Also, if the issue is clearly abandoned or in the wrong place you can `/assign` to have it assigned to yourself, and then `/close`.


We could also direct support requests to https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/

bgrant0607 · 2017-07-18T03:42:33Z

contributors/triage/guideline.md

+* `priority/important-soon` or `priority/important-longterm`  (P1 - High - functional error requiring quick fix)
+* `priority/backlog`  (P2 - Medium - error but not critical, small issue, for example, typo)
+* `priority/awaiting-more-evidence` (P3 - Low)
+* (P4 - Wishlist - not a real bug but suggestion or new feature request)


wishlist == awaiting-more-evidence

If we'd never, ever do it, just close.

bgrant0607 · 2017-07-18T03:43:48Z

contributors/triage/guideline.md

+* `priority/important-soon` or `priority/important-longterm`  (P1 - High - functional error requiring quick fix)
+* `priority/backlog`  (P2 - Medium - error but not critical, small issue, for example, typo)
+* `priority/awaiting-more-evidence` (P3 - Low)
+* (P4 - Wishlist - not a real bug but suggestion or new feature request)


Also, "fixes" of low-priority issues have non-trivial costs (reviews, babysitting, submit queue bandwidth, etc.), so if they really are very low priority, we shouldn't encourage anyone to work on them.

bgrant0607 · 2017-07-18T03:45:33Z

contributors/triage/guideline.md

+
+## Set ownership
+
+All issues should have an owner. If you are not sure of an owner, defer to the SIG label only. You can ping a team with an @ mention, like `@kubernetes/sig-cluster-lifecycle, can you have a look at this?` if you feel the issue should warrant a notification.


The teams are documented here:

https://github.com/kubernetes/community/blob/master/sig-governance.md#create-the-github-teams

The purpose could be documented better.

Please avoid using the *-misc teams as much as possible.

bgrant0607 · 2017-07-18T03:46:14Z

contributors/triage/guideline.md

+
+If you think you can fix the issue, assign it to yourself with just `/assign`.
+
+## Poke issue owner if PR is not created for it in 30 days


This should be automated.

kubernetes-retired/contrib#869

bgrant0607 · 2017-07-18T03:47:13Z

contributors/triage/guideline.md

+
+If you see any issue which is owned by a developer but a PR is not created in 30 days, a Triage engineer should contact the issue owner and ask for PR or release ownership.
+
+## Poke SIG if a SIG label is assigned to the issue but no one took ownership of it in 15 days


Everyone's responsibility == nobody's responsibility

We really need clear owners for this. Who is this section directed at?

This section is directed to the SIG - i.e. the issue has sig label but no response from SIG in certain numbers of days so poke/gently remind the SIG itself. As you said, it would be nice and helpful if we can have specific owner - a SIG lead, may be? Thanks!

I posted to the dev mailing list about extensions to OWNERS files about this

https://groups.google.com/d/msg/kubernetes-dev/su8MfL4PCYo/UPlCZGa4AQAJ.

Thoughts on requiring all sigs to have issue-escalation owners? One person per sig (maybe for a set period of time?!) whose responsible for routing issues within the sig?

This is also where metrics may come in handy. Might be nice to have an update in the community meeting once in awhile with sig-issue triage metrics and visualizations

I would think that as SIGs start to own parts of the code base that they would have oversight of the responsibilities of owning that, including issue management and escalation.

Should we perhaps make that explicit in the SIG charters that people mentioned in OWNERS are also responsible for issue triage, escalation and management?

timothysc · 2017-07-18T13:36:17Z

contributors/triage/guideline.md

+
+To read priorities in detail, please refer to the [Priorities](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#priorities).
+
+## Set ownership


Everything to this point has been a logical progression. Ideally you could reference a single logic flow chart that a bot could link and reference such that new contributors know what state the issue is in.

@timothysc thanks and are you referencing specifically to 'Define priority' section or all the sections so far? I am up for it, if you can help little more with re-write the way you are suggesting. /cc @castrojo

bgrant0607 · 2017-07-18T17:58:32Z

More background:

https://groups.google.com/forum/#!searchin/kubernetes-dev/issue$20triage|sort:relevance/kubernetes-dev/LEtIxeG0i84/Bk6vunrBBwAJ
https://groups.google.com/forum/#!searchin/kubernetes-dev/issue$20triage|sort:relevance/kubernetes-dev/jDSoBQLIy1U/Y1MVV8eJBgAJ
https://groups.google.com/forum/#!searchin/kubernetes-dev/issue$20triage|sort:relevance/kubernetes-dev/8pUqKMGcLY0/DYBUogbFBgAJ

bgrant0607 · 2017-07-18T18:02:22Z

@spzala

Please see:
https://github.com/kubernetes/community/blob/master/contributors/devel/pull-requests.md#6-squashing-and-commit-titles

When you squash and force push commits, reviewers can't tell what changes you made, and their comments also become detached from the text/code. Please don't squash again until this has been approved.

spzala · 2017-07-18T18:21:55Z

@bgrant0607 sure! Thought I will keep editing as get feedback, but good point. Sounds good, thanks!

jagosan · 2017-07-20T07:53:59Z

contributors/triage/guideline.md

+
+## Poke SIG if a SIG label is assigned to the issue but no one took ownership of it in 15 days
+
+If an issue has a SIG label assigned and no action is taken by SIG in 15 days (e.g. no comment was added by SIG or no discussion was initiated) then gently poke SIG about this pending issue. Also consider attending one of the SIG meetings if you feel this is appropriate.


Suggest this is a bot responsibility. Also suggest starting with an experiment to see if the poking has any effect.

castrojo · 2017-07-20T20:07:21Z

Ok we've gone over all the mentioned reviews (thanks everyone), and @spzala is working on a new commit that should address most of the straightforward ones.

Two outstanding issues:

a) Should we remove all the "manual notifications" sections in lieu of bots (existing or future?). If the automation doesn't exist then perhaps leaving it in there as a reminder might work? Or should we do a removal with the understanding that no one is manually keeping track of how ignored issues are being handled anyway and it's just adding length to this document. Then at some point someone will work on a bot that finds things that are over X days old and need triage/escalation?

b) Can we get a lazy consensus on the location of the file? (I personally don't feel strongly about either having it in a triage directory or if it's triage.md or combined with issues.md or not).

grodrigues3 · 2017-07-20T20:26:24Z

Can move to contributoris/devel and incorporate with the issues.md doc? Esp so we don't define the priority labels twice.

bgrant0607 · 2017-07-21T03:56:47Z

@castrojo Have any other changes been made to address feedback? It's still just one commit.

bgrant0607 · 2017-07-21T03:57:27Z

contributors/triage/guideline.md

+* Typing `/sig network` in a comment should add the sig/network label, for example.
+* Multiword SIGs use dashes, for example `/sig cluster-lifecycle`.
+
+## Validate if the issue is real


This only applies to bug reports, not to other types of issues.

bgrant0607 · 2017-07-21T03:59:48Z

contributors/triage/guideline.md

+
+If you think you can fix the issue and you are an issue reporter or a component organization member, assign it to yourself with just `/assign`. If you can not self-assign, leave a comment that you are willing to work on it and work on creating a PR.
+
+## Poke issue owner if PR is not created for it in 30 days


This is not realistic. The rate of issue submission is greater than the rate of resolution. Additionally, feature requests and other non-bugs probably will take multiple releases to resolve, in general. Issues that nobody is actively working on should definitely not have assignees.

@bgrant0607 For now, in new commit, didn't make much changes here. Totally agree with your comment but if there is a reasonable comment in the issue that it will take longer, then trigger won't bug SIG after initial touch base. If we need to make changes to text, I am good with it but for now created new commit with most feedback. Thanks!

bgrant0607 · 2017-07-21T04:00:09Z

contributors/triage/guideline.md

+
+## Poke SIG if a SIG label is assigned to the issue but no one took ownership of it in 15 days
+
+If an issue has a SIG label assigned and no action is taken by SIG in 15 days (e.g. no comment was added by SIG or no discussion was initiated) then gently poke SIG about this pending issue. Also consider attending one of the SIG meetings if you feel this is appropriate.


This is not realistic, either.

bgrant0607 · 2017-07-21T04:00:32Z

This is not ready to be merged.

And it needs to go in the devel subdirectory.

spzala · 2017-07-21T13:09:12Z

@bgrant0607 hi, no new commits/changes were made. @castrojo and I met yesterday to discuss all feedback and I am working on new commit. Also, as you suggested, yes, I will edit issues.md in devel subdir with these guidelines and update README of devel accordingly. Thanks!

spzala · 2017-07-21T20:47:45Z

@bgrant0607 hi, created a new commit. Hope did it as you suggested. Please take a look. I am sure it will take another round of feedback but have tried to take care of most feedback so far. Thanks!!

bgrant0607 · 2017-07-21T21:45:11Z

contributors/devel/issues.md

+For example, `@kubernetes/sig-cluster-lifecycle-bugs, can you have a look at this?`
+
+If you think you can fix the issue and you are an issue reporter or a component
+organization member, assign it to yourself with just `/assign`. If you can not


FYI, I created k8s-external-contributor as a placeholder for issues being worked on by non-members.

@bgrant0607 When an issue is assigned to k8s-external-contributor, how to known who is the k8s-external-contributor working on the issue? See example: kubernetes/kubernetes#8800 It's hard to find the real k8s-external-contributor. Seems like this label is not so useful as expected. The ideal way might be allowing non-members to be assigned directly.

bgrant0607 · 2017-07-21T21:45:54Z

contributors/devel/issues.md

+If you are not sure of who should own issue, defer to the
+SIG label only. If you feel the issue should warrant a notification,you can ping
+a team with an @ mention, in this format, `@kubernetes/sig-<group-name>-<group-suffix>`.
+Here the `<group-suffix>` can be one of `bugs, feature-requests,pr-reviews, test-failures, proposals`.


Should have a space before pr-reviews.

bgrant0607 · 2017-07-21T21:47:40Z

contributors/devel/issues.md

-release if it gets done, but we wouldn't block the release on it. A few days
-before release, we will probably move all P2 and P3 bugs out of that milestone
-in bulk.
+The above [priority](#define-priority) scheme still applies. P0 and P1 issues


The numerical priorities (P0, P1, etc.) should be changed to the verbose ones, but that could be done in a subsequent PR.

bgrant0607 · 2017-07-21T21:48:27Z

Thanks. LGTM. Please squash. You can fix the additional small details in a subsequent PR.

This guideline was initially created and proposed by Sahdev Zala and Jorge Castro. It has been discussed multiple times in the ContribX SIG meetings and via emails, and it incorporates all the suggestions. This PR is created per the latest SIG meeting discussion. The original open document with little bit more content is available here, https://docs.google.com/document/d/1dfZGGIsx4QrY8aaC1o2SNmMU6eQKS4xYg55xNLtHDmc/edit Co-Authored-By: Jorge Castro jorge@heptio.com Create Issue Triage Guidelines This guideline was initially created and proposed by Sahdev Zala (IBM) and Jorge Castro (Heptio). It has been discussed multiple times in the ContribX SIG meetings and via emails, and it incorporates all the suggesitons. The original open document with longer content is available here, https://docs.google.com/document/d/1dfZGGIsx4QrY8aaC1o2SNmMU6eQKS4xYg55xNLtHDmc/edit Create Issue Triage Guidelines This guideline was initially created and proposed by Sahdev Zala and Jorge Castro. It has been discussed multiple times in the ContribX SIG meetings and via emails, and it incorporates all the suggestions. This PR is created per the latest SIG meeting discussion. The original open document with little bit more content is available here, https://docs.google.com/document/d/1dfZGGIsx4QrY8aaC1o2SNmMU6eQKS4xYg55xNLtHDmc/edit Co-Authored-By: Jorge Castro jorge@heptio.com

spzala · 2017-07-22T04:52:29Z

@bgrant0607 yrw and Thank you!! Sounds great. Squashing and I will fix small details in a subsequent PR.

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes#787

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes/community#787

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes#787

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jul 6, 2017

k8s-ci-robot requested a review from castrojo July 6, 2017 22:01

cblecker reviewed Jul 6, 2017

View reviewed changes

cblecker mentioned this pull request Jul 7, 2017

k8s-ci-bot doesn't always reiterate the mentions to trigger a notification kubernetes/test-infra#2956

Closed

castrojo reviewed Jul 7, 2017

View reviewed changes

spzala force-pushed the triage branch from d9d36e6 to fc6bab5 Compare July 7, 2017 14:26

spzala changed the title ~~Create Issue Triage Guidelines~~ Create Issue Triage Guideline Jul 7, 2017

cmluciano reviewed Jul 7, 2017

View reviewed changes

spzala force-pushed the triage branch from fc6bab5 to 103e5f6 Compare July 10, 2017 17:09

grodrigues3 self-assigned this Jul 12, 2017

xiangpengzhao reviewed Jul 16, 2017

View reviewed changes

spiffxp reviewed Jul 17, 2017

View reviewed changes

bgrant0607 reviewed Jul 18, 2017

View reviewed changes

spzala force-pushed the triage branch from 103e5f6 to 934e5c1 Compare July 18, 2017 03:04

bgrant0607 self-assigned this Jul 18, 2017

bgrant0607 reviewed Jul 18, 2017

View reviewed changes

timothysc reviewed Jul 18, 2017

View reviewed changes

jagosan reviewed Jul 20, 2017

View reviewed changes

bgrant0607 assigned bgrant0607 and unassigned bgrant0607 Jul 21, 2017

bgrant0607 reviewed Jul 21, 2017

View reviewed changes

bgrant0607 closed this Jul 21, 2017

bgrant0607 reopened this Jul 21, 2017

spzala force-pushed the triage branch from a2829f8 to dc458ea Compare July 21, 2017 19:57

bgrant0607 reviewed Jul 21, 2017

View reviewed changes

spzala force-pushed the triage branch from dc458ea to 743d685 Compare July 22, 2017 04:56

bgrant0607 merged commit 35050d1 into kubernetes:master Jul 23, 2017

spzala added a commit to spzala/community that referenced this pull request Jul 24, 2017

Change numerical priorities to verbose

37d0f6a

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes#787

spzala added a commit to spzala/community that referenced this pull request Jul 24, 2017

Change numerical priorities to verbose

bd5cacb

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes#787

spzala mentioned this pull request Jul 24, 2017

Change numerical priorities to verbose #839

Merged

calebamiles pushed a commit to kubernetes/sig-release that referenced this pull request Jul 25, 2017

Change numerical priorities to verbose

b9fda9e

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes/community#787

erinboyd pushed a commit to erinboyd/community that referenced this pull request Oct 23, 2017

Change numerical priorities to verbose

1d5805c

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes#787

erinboyd pushed a commit to erinboyd/community that referenced this pull request Oct 23, 2017

Change numerical priorities to verbose

904aa5e

Change numerical priorities to verbose ones and fix a missing space as discussed under, kubernetes#787

danehans pushed a commit to danehans/community that referenced this pull request Jul 18, 2023

add-jjtischer to members.yaml (kubernetes#787)

8dc7d11


		## Set ownership

		All issues should have an owner, if you are not sure of an owner, then the SIG should assign one later down the line. You can ping a team with an @ mention, like `@sig-cluster-lifecycle, can you have a look at this?` if you feel the issue should warrant a notification.

		@@ -0,0 +1,13 @@
		# Kubernetes Issue Triage

		This directory contains Kubernetes Issue Triage Guideline and related documents.


		This directory contains Kubernetes Issue Triage Guideline and related documents.

		Triaging issues is a great way to get started contributing, and it will help you understand how the project is organized. Here’s a few predetermined searches for convenience:


		Speed up issue management.

		The Kubernetes issues are listed at https://github.com/kubernetes/kubernetes/issues. The issues are identified with labels. For example, an issue that belongs to SIG Network will eventually be set to label `sig/network`. New issues will start out without any labels. The detailed list of labels can be found at https://github.com/kubernetes/kubernetes/labels. While working on triaging issues you may not have privilege to assign specific label (e.g. `triaged`) and in that case simply add a comment in the issue with your findings.


		## Using the bot

		Most people do not have the ability to interact with the github issues and labels, for that we use a bot to manage labelling and triaging. The bot has a set of [commands and permissions](https://github.com/kubernetes/test-infra/blob/master/commands.md), this document will cover the basic ones.


		If you think you can fix the issue, assign it to yourself with just `/assign`.

		## Poke issue owner if PR is not created for it in 30 days


		## Determine if it’s a support request

		Sometimes users ask for support requests in issues; these are usually support requests for people who need help configuring some aspect of Kubernetes. These should be directed to our [support structures](https://github.com/kubernetes/community/blob/master/contributors/devel/on-call-user-support.md) and then closed. Only authors and assignees can `/close` an issue. Also, if the issue is clearly abandoned or in the wrong place you can `/assign` to have it assigned to yourself, and then `/close`.


		If you see any issue which is owned by a developer but a PR is not created in 30 days, a Triage engineer should contact the issue owner and ask for PR or release ownership.

		## Poke SIG if a SIG label is assigned to the issue but no one took ownership of it in 15 days


		To read priorities in detail, please refer to the [Priorities](https://github.com/kubernetes/community/blob/master/contributors/devel/issues.md#priorities).

		## Set ownership


		## Poke SIG if a SIG label is assigned to the issue but no one took ownership of it in 15 days

		If an issue has a SIG label assigned and no action is taken by SIG in 15 days (e.g. no comment was added by SIG or no discussion was initiated) then gently poke SIG about this pending issue. Also consider attending one of the SIG meetings if you feel this is appropriate.


		If you think you can fix the issue and you are an issue reporter or a component organization member, assign it to yourself with just `/assign`. If you can not self-assign, leave a comment that you are willing to work on it and work on creating a PR.

		## Poke issue owner if PR is not created for it in 30 days

Create Issue Triage Guideline #787

Create Issue Triage Guideline #787

Uh oh!

Conversation

spzala commented Jul 6, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

spzala commented Jul 6, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cblecker Jul 6, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spzala commented Jul 6, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

cblecker commented Jul 7, 2017

Uh oh!

spzala commented Jul 7, 2017

Uh oh!

castrojo left a comment

Choose a reason for hiding this comment

Uh oh!

spzala commented Jul 7, 2017

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

spzala Jul 7, 2017 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

spzala commented Jul 6, 2017 •

edited

Loading

cblecker Jul 6, 2017 •

edited

Loading

spzala commented Jul 6, 2017 •

edited

Loading

spzala Jul 7, 2017 •

edited

Loading