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 group 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.
and in that case simply add a comment in the issue with your findings.
Following are few predetermined searches on issues for convenience: * Longest untriaged issues (sorted by age) * Needs to be assigned to a SIG * Newest incoming issues * Busy untriaged issues (sorted by number of comments) * Issues that need more attention
These guidelines serves as a primary document for triaging incoming issues to Kubernetes. SIGs and projects are encouraged to either use these guidelines, or use this as a starting point if necessary. For example if your SIG has specific triaging needs, extend these guidelines. Note: These guidelines only applies to the kubernetes repository. Its usage for other github repositories related to Kubernetes is TBD.
Most people can leave comments and open issues. They don’t have the ability to set labels, change milestones and close other peoples issues. For that we use a bot to manage labelling and triaging. The bot has a set of commands and permissions and this document will cover the basic ones.
Sometimes users ask for support requests in issues; these are usually requests
from people who need help configuring some aspect of Kubernetes. These issues
should be labeled with
triage/support, directed to our support structures
(see below) and then closed. Also, if the issue is clearly abandoned or in the
wrong place, it should be closed. Keep in mind that only issue reporter,
assignees and component organization members can close issue. If you do not
have such privilege, just comment your findings. Otherwise, first
issue to yourself and then
Support requests should be directed to the following:
If you see support questions on firstname.lastname@example.org or issues asking for support try to redirect them to Stack Overflow. Example response:
Please re-post your question to [Stack Overflow] (http://stackoverflow.com/questions/tagged/kubernetes). We are trying to consolidate the channels to which questions for help/support are posted so that we can improve our efficiency in responding to your requests, and to make it easier for you to find answers to frequently asked questions and how to address common use cases. We regularly see messages posted in multiple forums, with the full response thread only in one place or, worse, spread across multiple forums. Also, the large volume of support issues on github is making it difficult for us to use issues to identify real bugs. Members of the Kubernetes community use Stack Overflow to field support requests. Before posting a new question, please search Stack Overflow for answers to similar questions, and also familiarize yourself with: * [user documentation](https://kubernetes.io/docs/home/) * [troubleshooting guide](https://kubernetes.io/docs/tasks/debug-application-cluster/troubleshooting/) Again, thanks for using Kubernetes. The Kubernetes Team
Components are divided among Special Interest Groups (SIGs). Find a proper SIG for the ownership of the issue using the bot:
/sig networkin a comment should add the sig/network label, for example.
Keep in mind that these commands must be on its own line and at the front of the comment.
Validate if the problem is a bug by reproducing it. If reproducible, move to
the next step of defining priority. You may need to contact the issue reporter
in the following cases:
* 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. Label such issues as
* If you can not reproduce the issue, label it as a
Contact the issue reporter with your findings and close the issue if both the
parties agree that it could not be reproduced.
* If you need more information to further work on the issue, let the reporter
know it by adding an issue comment followed by label
In all cases, if you do not get a response in 20 days then close the issue with an appropriate comment.
We use GitHub issue labels for prioritization. The absence of a priority label means the bug has not been reviewed and prioritized yet.
We try to apply these priority labels consistently across the entire project, but if you notice an issue that you believe to be incorrectly prioritized, please do let us know and we will evaluate your counter-proposal.
priority/critical-urgent: Must be actively worked on as someone’s top priority right now. Stuff is burning. If it’s not being actively worked on, someone is expected to drop what they’re doing immediately to work on it. Team leaders are responsible for making sure that all the issues, labeled with this priority, in their area are being actively worked on. Examples include user-visible bugs in core features, broken builds or tests and critical security issues.
priority/important-soon: Must be staffed and worked on either currently, or very soon, ideally in time for the next release.
priority/important-longterm: Important over the long term, but may not be currently staffed and/or may require multiple releases to complete.
priority/backlog: There appears to be general agreement that this would be good to have, but we may not have anyone available to work on it right now or in the immediate future. Community contributions would be most welcome in the mean time (although it might take a while to get them reviewed if reviewers are fully occupied with higher priority issues, for example immediately before a release).
priority/awaiting-more-evidence: Possibly useful, but not yet enough support to actually get it done. These are mostly place-holders for potentially good ideas, so that they don’t get completely forgotten, and can be referenced /deduped every time they come up.
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,
<group-suffix> can be one of
bugs, feature-requests, pr-reviews, test-failures, proposals.
@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
self-assign, leave a comment that you are willing to work on it and work on
creating a PR.
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 as needed.
Ideally the SIG lead should have a SIG member that is a first point of contact for SIG new issues. If an issue has a SIG label assigned and no action is taken by SIG in 30 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 and brig up issue, if you feel this is appropriate.
We additionally use milestones, based on minor version, for determining if a bug should be fixed for the next release. These milestones will be especially scrutinized as we get to the weeks just before a release. We can release a new version of Kubernetes once they are empty. We will have two milestones per minor release.
vX.Y: The list of bugs that will be merged for that milestone once ready.
vX.Y-candidate: The list of bug that we might merge for that milestone. A bug shouldn’t be in this milestone for more than a day or two towards the end of a milestone. It should be triaged either into vX.Y, or moved out of the release milestones.
The above priority scheme still applies. The
priority/critical-urgent issues are work we feel must get done before
issues are work we would merge into the release if it gets done, but we wouldn’t
block the release on it. A few days before release, we will probably move all
priority/important-longterm bugs out of
that milestone in bulk.
Issues that are identified as a support request, duplicate, not-reproducible
or lacks enough information from reporter should be closed following guidelines
explained in this file. Also, any issues that can not be resolved because of
any particular reason should be closed. These issues should have one or more
of following self-readable labels:
triage/support: Indicates an issues is not a bug but a support request.
triage/duplicate: Indicates an issue is a duplicate of other open issue.
triage/not-reproducible: Indicates an issue can not be reproduced as
triage/needs-information: Indicates an issue needs more information in
order to work on it.
triage/unresolved: Indicates an issue that can not be resolved.
A triage engineer should add these labels appropriately. Kubernetees GitHub Org members can search open issues per these labels to find ones that can be quickly closed.
Also note that,
fejta-bot will add
lifecycle/stale label to issues with no
activity for 90 days. Such issues will be eventually auto closed if the label is
not removed with the
/remove-lifecycle stale label or prevented with the
/lifecycle frozen label. Refer to the
fejta-bot added comments in the issue
for more details. It is fine to add any of the
triage/* labels described in
this issue triage guidelines to issues triaged by the
fejta-bot for a better
understanding of the issue and closing of it.