WIP: basic backlog management #52
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,122 @@ | ||
| # Backlog Structure for OpenTelemetry | ||
|
|
||
| It's an important community goal for OpenTelemetry that our members find the backlogs to be responsive, and easy to take part in. Having a shared methodology for processing issues helps new members understand the current state of each project. | ||
|
|
||
| ## Roles | ||
|
There was a problem hiding this comment. I took these roles from the OC doc, but perhaps we want to make them align more clearly with what is listed in https://github.com/open-telemetry/community/blob/master/community-membership.md. |
||
| * **Triager**: Person who is triaging the issue by determining its workability. This person is responsible for getting the ticket to one of two stages - 1) ready-for-work 2) wontfix. They are responsible for triaging by working with the OP to get additional information as needed and analyzing the issue and adding relevant details/information/guidance that would be helpful to the resolution of the issue. | ||
|
There was a problem hiding this comment. there is one more category of issues - "should be defined in specs first". Typically when someone suggests new API surface There was a problem hiding this comment. There is no formal There was a problem hiding this comment. These work stages don't match the issue states below, looks like separate docs glued together. |
||
|
|
||
| * **OP**: Original Poster. This is the person who has opened or posted the issue. | ||
|
|
||
| * **Contributor**: Person(s) that are actually doing the work related to the ticket. Once work is done, they work with the Reviewer and the Contributing Reviewers to get feedback implemented and complete the work. They are responsible for making sure issue status label is up to date. | ||
|
|
||
| * **Reviewer**: Person(s) whose Approval is needed to merge the PR. | ||
|
|
||
| * **Contributing Reviewer**: Person who provides feedback on an PR but whose Approval is not necessarily needed to merge the PR. | ||
|
|
||
| ## SLAs | ||
|
There was a problem hiding this comment. Another approach to SLAs would be to assign them them to each issue state, rather than each role. ¯_(ツ)_/¯ |
||
| We value having a responsive backlog, and have response SLAs for each role. If an issue exceeds an SLA, it is put into the `stale` state. | ||
|
|
||
| * **Triager**: Daily (Business Days) review of new issues with initial feedback to OP or issue processed within 3 days of last activity. | ||
| * **Reviewer / Contributing Reviewer**: Provide feedback within 3 days of the last activity on a PR | ||
| * **Contributor**: 3 day updates as comments on the PR to indicate activity | ||
|
|
||
| ## Issue States | ||
|
|
||
| ### New | ||
| label: `new` | ||
|
There was a problem hiding this comment. why do we need a label for new? Perhaps anything without the label is new |
||
|
|
||
| New issues are the domain of the backlog Triagers. Every new issue should be responded to quickly, with a greeting and any needed clarifying questions. If assessing the issue requires more information, the Triager collaborates with the OP until workability is determined. | ||
|
|
||
| The most common next steps for new tickets: | ||
| * `available` for actionable work items. | ||
| * `needs-discussion` for issues which cannot be triaged quickly, but raise important points. | ||
| * `no-further-action` for issues which can be quickly resolved. | ||
|
|
||
|
|
||
| ### Available | ||
| label: `available` | ||
|
There was a problem hiding this comment. can we use |
||
|
|
||
| For new work requests Once it has been classified, a ticket is up for grabs to be picked up to be worked on by a contributor. | ||
|
There was a problem hiding this comment. "Once a new work request has been classified any contributor may begin work on it" makes more sense than "... a ticket is up for grabs to be picked up to be worked on by a contributor" if we're not using |
||
|
|
||
| All work is labeled with a priority: | ||
| * `P0` = Critical (Drop everything and work on it.) | ||
| * `P1` = Important (Work on it if no P0 are present. Use judgment to prioritize items within a list of P1s) | ||
| * `P2` = Low (Work on it when no P1 are left or some one from community wants to contribute) | ||
|
There was a problem hiding this comment. Nit: periods are inconsistent here |
||
|
|
||
| Work can also be classified into a number of categories, to make available issues easier to find. Common examples of work categories are: | ||
| * `feature-request` | ||
|
There was a problem hiding this comment. what's the difference with |
||
| * `enhancement` | ||
| * `bug` | ||
| * `docs` | ||
|
|
||
| Available work can be assigned in the following ways: | ||
| * A contributor assigns the ticket to themselves. | ||
| * A maintainer assigns the ticket to a contributor. | ||
|
|
||
| All tickets transition to `wip` once they have been assigned. | ||
|
|
||
| ### WIP | ||
| label: `wip` | ||
|
|
||
| Any ticket which has been assigned a lead contributor is considered work in progress. | ||
|
There was a problem hiding this comment. do you envision some automation? There was a problem hiding this comment. Also - non-members can declare that they are working on issue by mentioning themselves in comments. It is mentioned in CONTRIBUTING.md |
||
|
|
||
| * If a PR is merged which resolves the issue, the ticket can be closed as `completed`. | ||
| * If work is blocked on review, the ticket transitions to `needs-review`. | ||
| * If work is abandoned, or the ocntributors otherwise change their minds, the ticket can be closed as `no-further-action`. | ||
|
|
||
|
|
||
| ### Needs Review | ||
| label: `needs-review` | ||
|
|
||
| Implementation work related to the ticket has been completed. Work related to a Review and/or any changes requested as part of the review is in progress. Issues with a PR associated with it will be considered as in ‘In Review’. | ||
|
There was a problem hiding this comment. same question - "considered There was a problem hiding this comment. I feel this is related to SLAs. Ideally, no state change from “wip” is needed. However, if an issue becomes blocked on review activity, it’s state should change. I would like automation to track SLAs, and assign labels in response. But the task should be simple enough for a triager to manually. There was a problem hiding this comment. so you want to solve the problem that the issue become "stale" in There was a problem hiding this comment. Was |
||
|
|
||
| * Move the issue back to `in-progess` if significant changes are needed. | ||
|
|
||
| * Close the issue with the `completed` label. | ||
| * Close the issue with the `no-action` label. | ||
|
|
||
| ### Needs Discussion | ||
| label: `needs-discussion` | ||
|
|
||
| Some issues are not directly related to a particular code change. This can often arise with tickets describing unclear edge cases, and situations where applying OpeTelemetry is proving to be difficult. If a ticket is worth considering in the issue backlog, but not scoped clearly enough to move to `wip`, then it `needs-discussion`. | ||
|
|
||
| * When possible, move the discussion forwards by using code examples. | ||
|
|
||
| * Mark the ticket as `agreed` if a resolution is found. | ||
| * Close the ticket as `no-action` if discussion ends without a solution. | ||
| * Note: If the ticket is a help request with an existing answer, please link to the answer before closing the ticket. | ||
|
|
||
| ### Agreed | ||
| label: `agreed` | ||
|
|
||
| An agreement has been reached. Once a course of action is determined, discussion is (hopefully) over. | ||
|
|
||
| * Clearly list any resulting action items which need to be adressed. | ||
| * Close the ticket once all action items are completed. | ||
|
|
||
| ### Stale | ||
| label: `stale` | ||
|
|
||
| When a ticket has violated an SLA, it becomes stale. | ||
|
There was a problem hiding this comment. do you envision some automation in place? There was a problem hiding this comment. For SLAs, yes. But it should be possible to do by hand, or it is too complicated. For next step, I suggest we try setting up project boards for java and c#, and model some of this workflow. There was a problem hiding this comment. this SLA tag is clearly have some target in mind. You want to ensure "healthy" project with timely replies. If somebody will do it by hand - repo is already "healthy". Your issue will be read and classified. So from my perspective SLA like this can mostly be used as a metric for transparency or reminder to the maintainer with suggested actions. This is how I read the proposal in your document. Comment with the mention of maintainer and triager like this can be posted on the issue: Like this isssue was untriaged for a long time. (at)poster - please make sure the ticket has enough details and, when possible, clear steps to repro. (at)repo-maintainers If you feel that some details are missing - add this "label". If it takes too much time to reproduce - please indicate that you are looking into it using this "label"., etc... But this thing will only be useful with automation |
||
|
|
||
| Action items for stale tickets: | ||
| * record the SLA details as comment on the ticket. | ||
| * @mention the person(s) who can resolve the SLA. | ||
|
|
||
| ### Blocked | ||
| label: `blocked` | ||
|
|
||
| An Issue is blocked due to an external reason or extenuating circumstances. Genereally, issues should be closed as `no-further-action`, rather than be left in a `blocked` state. | ||
|
|
||
| ### No Futher Action | ||
| label: `no-further-action` | ||
|
|
||
| Not every discussion or feature request results in action. Issues which cannot be adressed at the present moment, or have no futher discussion, should be closed. This helps keep the open backlog focused on active discussions. | ||
|
|
||
| Possible reasons: | ||
| * a prior discussion decided the issue for now. | ||
| * a discussion is off topic. | ||
| * a feature request is not implementable. | ||
|
|
||
| In these cases, close the ticket as `no-further-action`. Please include a description explaining why the ticket was closed, including links to prior tickets if available. Please describe how the ticket can be reopened if needed. | ||
|
|
||
| ### Completed | ||
| label: `completed` | ||
|
|
||
| Any issues which are resolved via a merged pull request can be closed with the `completed`. This extra label can be helpful when searching closed issues. | ||
|
There was a problem hiding this comment. can you please elaborate on it? So you want to differentiate in search wether issue was There was a problem hiding this comment. Mainly, this is here because, like “new,” completed is an important state. I agree that we can use “closed with no label” to mean “completed” if it is too difficult to add a label. As to why the label is an important category, when searching the past it is important to scope search to work that was incorporated into the project, versus off-topic discussions or rejected features. Closed labels:
There was a problem hiding this comment. I'm curious what kind of a search do you have in mind? Looking for some exception from SDK, but only when it resulted in "completed" PR? I see how it can be useful for analytics. Perhaps we can identify what kind of analytics we need to run to inform what kind of additional work to impose on maintainers |
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
it will be great to state the goals of the process. What we are optimizing for.