Skip to content

Instantly share code, notes, and snippets.

@jsquire

jsquire/issue-rules.md

Last active July 21, 2023 16:24
Show Gist options
  • Save jsquire/f8ffbdfbf217279ad5fdd718bbfa6929 to your computer and use it in GitHub Desktop.
Save jsquire/f8ffbdfbf217279ad5fdd718bbfa6929 to your computer and use it in GitHub Desktop.
Download ZIP
# Azure SDK for .NET repository issue rules and process
Raw
issue-rules.md

Azure SDK for .NET repository issue rules and process

Goal

This document attempts to define the set of rules used for triaging and managing issues in the Azure SDK for .NET repository. These rules were once part of a standardized process owned by Alex Ghiondea and were at least loosely followed in the other language repositories. It is unknown whether there has been drift in the processes between languages since.

History

At one point, these were documented in OneNote and then moved to a DevOps wiki, and then moved again. I do not know where the documentation exists today - if it still does. All that I'm aware of is a high-level view of the process.

A set of reports that evaluated this rule set and alerted repository owners to data quality issues used to run weekly, but died a long while back. The reporting framework was not well understood and has proven to be difficult to update. In addition to the data quality issues, there were 3-4 other reports for incoming issues, (outdated) SLA metrics, and some other reasons.

In my opinion, there was more noise than help to the reports, so when they died, EngSys and I decided not to try to resurrect them. The original source continues to exist in the tools repository for historical purposes, since it was largely the only documentation on the rules themselves. The deployment process is documented, but may not be up-to-date.

Document conventions

  • Customer Issue: An issue that was opened by someone outside of the Azure SDK team - or as close as our automation can identify.

  • Issue Owner: The Azure SDK or partner team member assigned to evaluate and work the issue after initial triage.

  • Issue Author: The individual who opened the issue.

  • Area Label: A label that identifies an Azure SDK package or associated service. These are the pink ones (#e99695). Also known as "service labels" by some.

  • Category Label: A label that identifies a category (client, management, service). These are the yellow ones (#ffeb77).

  • Type Label: A label that attempts to classify the type of issue. (question, bug, feature-request). These are the orange ones (#eaa875).

Issue scenarios

Customer issues

  • As with all other issue types, customer issues must have exactly one area label and exactly one category label assigned at triage. These are used to determine how to route the issue to the responsible party so that it receives attention. The CODEOWNERS file in each repository is intended to drive this routing and should identify the individuals or team who will own next steps.

  • Customer issues are required to have exactly one type label for their entire lifetime until closed. At triage, question is always assigned. It is up to the owner of the issue to evaluate the context and update the type to bug or feature-request as appropriate.

  • Customer issues are always tagged with customer-reported on triage and will retain this label until closed, regardless of the type that is identified.

  • Customer issues tagged as bug or question are required to have exactly one of the following for their lifetime until closed. The label will change as work is done and the context shifts:

    • needs-team-attention: Indicates that the owner of the issue is responsible for next steps. No automated actions are performed, the owner is responsible for tagging as needs-author-feedback or issue-addressed as appropriate and/or closing the issue.

    • needs-author-feedback: Indicates that more information is needed from the issue author and assistance is blocked until we receive it. The issue author is responsible for next steps. When the author responds, automation tags as needs-team-attention. If the author does not provide the needed information, the issue is closed by automation.

    • issue-addressed: Indicates that the owner of the issue believes that assistance has been provided and no further action is needed. The issue author may be unresolved to reset to needing team attention. If not unresolved, the issue is closed by automation.

  • Customer issues tagged as bug or feature-request must be assigned to a milestone.

  • Customer issues tagged as question may NOT be assigned to a milestone.

  • Customer issues tagged as feature-request are not covered by an SLA and may be long-lived. They should be manually closed if the team decides that this is not a feature that we plan on including in the product.

  • Customer issues tagged as bug or question are covered by an SLA. It is unknown if SLA metrics account for time spent needs-author-feedback and issue-addressed where our team is either blocked or has completed work.

  • Customer issues unrelated to Azure SDK .NET packages - such as service or portal issues - should guide the author to opening an Azure support request and the issue closed. Our goal is to ensure that customers receive prompt support and attention, which does not happen when we tag Service Attention on an issue and assume the service team will take ownership. This is true whether we understand this at initial triage or discover that the root cause of something is not related to the SDK as we work the issue.

  • Customer issues tagged feature-requests and will not be worked on by the Azure SDK team in the short term are encouraged to tag with help wanted and good first issue if appropriate. This will help to guide community contributors to features that we'd like but are lower priority.

Partner team issues

  • As with all other issue types, partner issues must have exactly one area label and exactly one category label assigned at triage. These are used to identify the responsible party so that it can be tracked.

  • Issues opened by customers for packages owned by partner teams should be tagged with Service Attention and otherwise follow the Customer issues rules.

  • Partner team issues that are internal work items or backlog features are not covered under an SLA and may be long-lived. These issues should be evaluated periodically and closed if the team no longer believes they should be added to the product.

  • Partner teams that own their SDK and use repository issues to manage work are required only to have the area and category labels. They may or may not choose to use bug, feature-request, and Service Attention. In the majority of cases, they do not.

  • Partner team issues that are internal work items or backlog features are required to be assigned a milestone, regardless of whether or not a type label was used.

  • Partner team backlog issues which are "nice to have" and not on the short-term road map are encouraged to tag with help wanted and good first issue if appropriate. This will help to guide community contributors to features that we'd like but are lower priority.

Azure SDK team issues

  • As with all other issue types, team issues must have exactly one area label and exactly one category label assigned at triage. These are used to identify the responsible party so that it can be tracked.

  • Issues opened by customers for packages owned by the Azure SDK team should follow the Customer issues rules. A team member to own the issue will be assigned as part of initial triage.

  • Team-owned issues for tracking work and backlog items are not covered under an SLA and may be long-lived. These issues should be evaluated periodically and closed if the team no longer believes they should be added to the product.

  • Team-owned issues for managing work and tracking upcoming features are required only to have the area and category labels. They may or may not choose to use bug and feature-request. In the majority of cases, they do not.

  • Team issues that are internal work items or backlog features are required to be assigned a milestone, regardless of whether or not a type label was used.

  • Backlog issues which are "nice to have" and not on the short-term road map are encouraged to tag with help wanted and good first issue if appropriate. This will help to guide community contributors to features that we'd like but are lower priority.

Known gaps and challenges

  • We do not know what other process and reports may have dependencies on these rules being followed. Outside of the GitHub automation and (now dead) reports, I cannot say if there is anything related to SLA/metrics reporting or other automation/tooling that has assumptions based on these. In short - I have no idea what may break or be broken.

  • The rule set is not well understood and not consistently followed. Many adjustments are made during triage or follow-up passes. This was true when documentation existed, and remains true now that the details have been lost.

  • It has been a challenge to align both Azure SDK and partner team members. Even well-known patterns like "assign a pink and yellow to issues that you open" are not consistently followed. Any revisions to this rule set should keep this in mind. For example, one idea that has been mentioned is asking team members to add additional metadata labels to help classify issues. In my opinion, this will struggle to be successful.

  • There's a strong association between our repository automation and the rule set. Any changes that we make to these rules will likely require automation adjustments as well. The process and rules will need to stay within the capabilities of our automation and reporting.

References and resources

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment