WIP: basic backlog management #52
Conversation
docs/project-backlog.md
Outdated
|
|
||
| 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.
docs/project-backlog.md
Outdated
|
|
||
| * **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. ¯_(ツ)_/¯
docs/project-backlog.md
Outdated
| ## 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
docs/project-backlog.md
Outdated
| * `no-further-action` for issues which can be quickly resolved. | ||
|
|
||
| ### Available | ||
| label: `available` |
There was a problem hiding this comment.
can we use up-for-grabs?
docs/project-backlog.md
Outdated
| * `P2` = Low (Work on it when no P1 are left or some one from community wants to contribute) | ||
|
|
||
| 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?
docs/project-backlog.md
Outdated
| ### 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
docs/project-backlog.md
Outdated
| ### 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
docs/project-backlog.md
Outdated
| ### 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 In Review" - is there manual step for this? If so - it sounds heavyweight process. If there is an automation - how it will understand issue to PR association?
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 wip state? If there is an automation that will bug me to change the state - I will do it. Otherwise - it looks like too much to do to fix a simple bug (for instance).
docs/project-backlog.md
Outdated
| ### 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 completed or closed with explanation of user error? Typically you don't care, just read comments and associated PRs should be enough
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:
- record of work. (completed)
- record of non-work requests. (no-further-action)
- record of issues closed without due process. (no label)
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
docs/project-backlog.md
Outdated
| 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 | ||
| * **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
docs/project-backlog.md
Outdated
| 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 | ||
| * **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 no formal Triager in community membership document. My first reaction is that we should just make it maintainer's responsibility. However I can see cases when someone helping maintainers with triage. If you envision this situation - it will be good to mention it in community membership document
docs/project-backlog.md
Outdated
|
|
||
| * 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`. |
docs/project-backlog.md
Outdated
| ### 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.
Was In Review removed as an issue state?
docs/project-backlog.md
Outdated
|
|
||
| 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’. | ||
|
|
||
| * Move the issue back to `in-progess` if significant changes are needed. |
docs/project-backlog.md
Outdated
|
|
||
| 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. |
docs/project-backlog.md
Outdated
| 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. |
docs/project-backlog.md
Outdated
| ### Available | ||
| label: `available` | ||
|
|
||
| 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 up-for-grabs.
docs/project-backlog.md
Outdated
| 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 | ||
| * **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.
These work stages don't match the issue states below, looks like separate docs glued together.
docs/project-backlog.md
Outdated
| 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
@tedsuo as you are a maintainer of Go repo - perhaps you can start there and demonstrate how it may be working and benefits of using specific tags |
docs/project-backlog.md
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
it will be great to state the goals of the process. What we are optimizing for.
|
Hi all. After a number of discussions, I've re-written this as a simpler proposal. It focuses on two major flows - Code Changes and Discussions - and how to handle issues that get stuck. I also switched to only using roles that appear in https://github.com/open-telemetry/community/blob/master/community-membership.md. Please think about what steps only a project Maintainers should do, vs what any community member should be allowed to do. Please let me know if this more stream-lined proposal works as a starting point for a common backlog management procedure. We can always add more detail and process later, as the project grows. |
| * 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. If a PR is merged which resolves the issue, the issue can be closed. If work is abandoned, or the contributors otherwise change their minds, the ticket should be closed as `no-further-action`. |
There was a problem hiding this comment.
Shouldn't the ticket transition back to up-for-grabs if the work is abandoned?
There was a problem hiding this comment.
Is there a conflict here with the stale label?
There was a problem hiding this comment.
Good point, wip should go to up-for-grabs if the PR is abandoned. It should go to no-further-action only if the contributors change their mind about the value of the Issue itself.
What conflict with stale do you mean? Could you describe?
There was a problem hiding this comment.
"Work is abandoned" may manifest as exceeding SLA (contributors don't comment on PR for 3 days), so the issue should move to stale.
| ## New Issues | ||
|
|
||
| Flow: | ||
| * An issue is filed by a community member. |
There was a problem hiding this comment.
Does it have to be a community member? Anyone can file an issue, no?
| Flow: | ||
| * A new issue is filed, proposing a code change. | ||
| * Maintainer labels the issue as `up-for-grabs`; reviewers are assigned. | ||
| * `up-for-grabs` becomes `wip` once a Collaborator is assigned. |
There was a problem hiding this comment.
How about adding an assignee and then leveraging a Github project board? It can move the issue automatically to an in-progress section (concerned about process overhead here).
There was a problem hiding this comment.
Or people just mention themselves in comments. Not everybody is OpenTelemetry project member
|
|
||
| Flow: | ||
| * An existing issue gets stuck due to a lack of response. | ||
| * The `stale` label is applied, and the appropriate members contacted. |
There was a problem hiding this comment.
What are the plans to automatic this process?
| * record the SLA details as comment on the ticket. | ||
| * @mention the person(s) who can resolve the SLA. | ||
|
|
||
| Sometimes, an issue cannot move forwards is due to an external reason or extenuating circumstances. For example, waiting on work to be finished in another project. In these cases, the `blocked` label is used instead. Preferably, issues should be closed, rather than be left for long periods in a `blocked` state. |
There was a problem hiding this comment.
What are the plans to automatic this process?
| @@ -0,0 +1,79 @@ | |||
| # Issue Management 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. | |||
There was a problem hiding this comment.
Having a shared methodology for processing issues helps new members understand the current state of each project
I don't understand this goal:
- Do you mean it will help contributors (members). Or it also will help end users?
- Do you propose some metric that new member can evaluate? Or the project state will be expressed by number of stale issues?
Maybe just replace the entire sentence with "Shared practices will simplify collaboration and engagement as well as help standardize on automation and overall project management."
|
|
||
| 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. | ||
|
|
||
| SIGs are encouraged to experiment with labels and backlog management procedures. This document only covers the bare bones of issue management which should work the same across all SIGs, to help maintain a responsive backlog and allow us to track work across all projects in a similar manner. |
There was a problem hiding this comment.
SIG is for group of people with similar interests. I think you need to use "repository" here instead
| Flow: | ||
| * An issue is filed by a community member. | ||
| * A maintainer responds and asks clarifying questions. | ||
| * The maintainer processes the issue as a Code Change, a Discussion, or resolves it quickly. |
There was a problem hiding this comment.
next sentence saying that it will be a triager, not maintainer role. Which one do you propose?
| * A maintainer responds and asks clarifying questions. | ||
| * The maintainer processes the issue as a Code Change, a Discussion, or resolves it quickly. | ||
|
|
||
| Every new issue should be responded to quickly by a Maintainer, 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. If the ticket is a help request with an existing answer, please link to the answer before closing the ticket. |
There was a problem hiding this comment.
define OP on a first use.
|
|
||
| A ticket becomes `up-for-grabs` once a maintainer deems it is processed sufficiently that work can begin. Issues should be well scoped and have clear goals. | ||
|
|
||
| A ticket labeled `up-for-grabs` can be picked up by anyone in the community. Available work can be assigned in the following ways: |
There was a problem hiding this comment.
by everyone really. Community membership has a requirement to send couple PRs =)
|
|
||
| All tickets transition to `wip` once they have been assigned. If a PR is merged which resolves the issue, the issue can be closed. If work is abandoned, or the contributors otherwise change their minds, the ticket should be closed as `no-further-action`. | ||
|
|
||
| ## Discussions |
There was a problem hiding this comment.
please cover the case of spec-needed label like here: open-telemetry/opentelemetry-js#5
|
|
||
| Flow: | ||
| * A new issue is filed, raising an important question. | ||
| * Maintainer labels the issue as `needs-discussion`. |
There was a problem hiding this comment.
github suggests to mark it as question. needs-discussion is OK.
There was a problem hiding this comment.
Question is better reserved for help tickets.
|
|
||
| Every new issue should be responded to quickly by a Maintainer, 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. If the ticket is a help request with an existing answer, please link to the answer before closing the ticket. | ||
|
|
||
| ## Code Changes |
There was a problem hiding this comment.
call it enhancement - this is the label GitHub created out of the box?
| Sometimes, an issue cannot move forwards is due to an external reason or extenuating circumstances. For example, waiting on work to be finished in another project. In these cases, the `blocked` label is used instead. Preferably, issues should be closed, rather than be left for long periods in a `blocked` state. | ||
|
|
||
| ## Closing an Issue | ||
| Any issues which are resolved via a merged pull request can simply be closed. |
There was a problem hiding this comment.
... or no reply from OP for a while
| * `up-for-grabs` becomes `wip` once a Collaborator is assigned. | ||
| * Closed once all PRs are accepted. | ||
|
|
||
| A ticket becomes `up-for-grabs` once a maintainer deems it is processed sufficiently that work can begin. Issues should be well scoped and have clear goals. |
|
|
||
| Flow: | ||
| * A new issue is filed, raising an important question. | ||
| * Maintainer labels the issue as `needs-discussion`. |
There was a problem hiding this comment.
Question is better reserved for help tickets.
| * If discussion happens elsewhere, record relevant meeting notes into the issue. | ||
| * When an agreement is made, clearly summarize the decision, and list any resulting action items which need to be addressed. | ||
|
|
||
| ## When Issues get Stuck |
There was a problem hiding this comment.
What about issues that are asking for things not on the immediate roadmap? Ie yes we'd like to support this, but have already 6 month of work ahead of us.
|
Let's move this document discussion to the specification repository. Technical Committee will be deciding on this process. Please re-submit this doc there. |
This is based on @jparsana's excellent triage documentation from OC: https://github.com/census-instrumentation/opencensus-specs/blob/master/triage-process.md
The main change was to move from a table format to a format that allowed for more details about each stage. (open to other formatting options!) I also added more stages related to triaging discussions.
This is currently a WIP, I've added some questions as inline comments.