Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adding draft SLA to issue-management.md file #163

Merged
merged 15 commits into from
Jul 31, 2019
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ OK on GitHub.
We highly encourage to use line breaks in markdown files at `80` characters
wide. There are tools that can do it for you effectively. Please submit proposal
to include your editor settings required to enable this behavior so the out of
the box settings for this repository will be consistent.
the box settings for this repository will be consistent.
93 changes: 93 additions & 0 deletions issue-management.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,93 @@
# 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. Shared practices will simplify collaboration
and engagement as well as help standardize on automation and overall project management.

SIGs are encouraged to experiment with labels and backlog management procedures,
including project board. 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.


## Roles

- OP:
- Original Poster. This is the person who has opened or posted the issue.
- Maintainer (aka Triager, or anyone performing that role):
- Person who is triaging the issue by determining its workability. This person is
responsible for getting the tickets to one of two stages - 1) `help-wanted`
2) `will-not-fix`. 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.
- Collaborator:
- Person(s) that are actually doing the work related to the ticket. Once work is done,
they work with the Reviewer to get feedback implemented and complete the work. They
are responsible for making sure issue status labels are up to date.
- Reviewer:
- Person whose Approval is needed to merge the PR.


## Opening an Issue

- An issue is filed by OP.
- A Maintainer responds and asks clarifying questions within 1-2 business days.
- The Maintainer processes the issue and labels it as:
- `bug`
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
- `enhancement`
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
- `need-discussion`
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
- `documentation` or
- `will-not-fix` (thereby closing the issue with explicit reasons)
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
- The Maintainer can also label the issue as
- `URGENT` (for critical issues)
- `help-wanted` for issues which require work and have no one assigned
- Once a Collaborator is assigned, please remove `help-wanted` and add `wip` to
the issue.
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved


## Closing an Issue

- Review criteria:
- For interface and design changes: 2 approvals - which must be from reviewers
who work at different companies than the Collaborator.
- For smaller or internal changes: 1 approval from a different company.
- For `URGENT` issues:
c24t marked this conversation as resolved.
Show resolved Hide resolved
- Collaborator: please provide initial assessment of the issues to OP ASAP or
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
within 1 business day, whichever is earlier.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"ASAP or within X" seems to have the same logic as "up to X% off or more" -- it could describe any number.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The intention here is to highlight the request for quick response while stating the upper limit. Let me know your thoughts.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How about something like this?

"Please provide an initial assessment of the issue within 1 business day. URGENT issues are time-sensitive. Collaborators should prioritize the assessment and responses to review comments above other work and respond as quickly as possible."

"As quickly as possible" still feels fishy to me since this is what SLAs are meant to solve.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Understood @c24t . Given this is community based and not really the same as enforceable within one company, suspect this is as good as we can get in terms of prescribing the intent. One question is while this sounds better and more descriptive as well, do you (or anyone else) feel comfortable duplicating this, with some minor adjustment, 2 other times for URGENT issue SLA vs the existing shorter versions? For other minor comments above, I am planning to resolve them to move things along. Let me know otherwise or feel free to re-open if you have strong feelings on those. Thanks again for spending the time to provide input.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@c24t let me know your thoughts on this. Would like to get this merged soon. Thanks in advance.

- Reviewer: please review and provide feedback ASAP or within 1 business day,
whichever is earlier.
- Collaborator: please provide update and/or responses to review comments ASAP
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
or within 1 business day, whichever is sooner. Merge should happen as soon as
review criteria are met.
- For non-`URGENT` issues
- Collaborator: please provide initial response or assessment of the issue to
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
OP within 3 business days.
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
- Reviewer: please review and provide feedback within 3 business days.
- Collaborator: please provide update and/or responses to review comments
thomashchan1 marked this conversation as resolved.
Show resolved Hide resolved
within 3 business days. Once all review comments are resolved, please allow
1-2 business days for others to raise additional comments/questions, unless
the changes are fixing typos, bugs, documentation, test enhancements, or
implementing already discussed design.

When closing an issue that we `will-not-fix` or we believe need no further
action, please provide the rationale for closing, and indicate that OP can
re-open for discussion if there are additional info, justification and
questions.


## When Issues Get Stuck

Some issues are not directly related to a particular code change. If an
issue is worth considering in the issue backlog, but not scoped clearly
enough for work to begin, then please label it `need-discussion`.

- When possible, move the discussion forward by using tests and code examples.
- 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.

If an issue is stuck because someone is not responding, please add the `stale`
label. It is possible to automate this. E.g. https://github.com/apps/stale
The minimum time elapsed before the `stale` label is applied is proposed to be
one week.