wpf/Documentation/issue-guide.md

Issue Guide

This page outlines how WPF team thinks about and handles issues. For us, issues on GitHub represent actionable work that should be done at some future point. It may be as simple as a small product or test bug or as large as the work tracking the design of a new feature.

We will keep issues open even if the WPF team internally has no plans to address them in an upcoming release, as long as we believe they are in line with our direction.

How to file issues

You can help us streamline our response time to your feedback and ideas by filing high-quality reports.

High-quality bugs

In general, try to be specific. Get straight to the main point. Leave additional details, options and alternatives to the end (hint: separate them visually). Don't write long bug reports, unless you have to.

• Include a minimal repro in your bug if at all possible (chop off dependencies, remove as much code as possible). If it is not possible, say why.
  • Note: Yes, it may take some time to minimize a repro from your larger app - but that is exactly what we would do in most cases anyway. Issues with clear small repros are easier for us to reproduce/investigate and therefore have higher chance to be addressed quickly.
• Include callstacks, symptom description, or what is the difference between actual and expected behavior.

High-quality features and API suggestions

Provide clear description of your suggestion. Explain scenarios in which it would be helpful and why (motivation). Ideally, assume that the reader has minimal knowledge and experience with writing apps/libraries that would benefit from the feature.

For API suggestions, check API review process, especially example of good API proposals.

Labels

We use GitHub labels on our issues in order to classify them. We have the following categories per issue:

• Issue Type: These labels classify the type of issue. We use the following types:
  • api-suggestion: Issues which would add new APIs (see API Review process for details).
    • Note: WPF API process is not finalized yet. We may need to add additional UI-specific steps to it (e.g. accessibility review). Expect finalized API review process post-3.0 when we will be ready to take new APIs.
  • bug, enhancement, test-bug, test-enhancement, question, documentation: See label description for details.
• Other:
  • up-for-grabs: Smaller sections of work which we believe are well scoped. These sorts of issues are a good place to start if you are new. Anyone is free to work on these issues.
  • needs-more-info: Issues which need more information to be actionable. Usually this will be because we can't reproduce a reported bug. We'll close these issues after a little bit if we haven't gotten actionable information, but we welcome folks who have acquired more information to reopen the issue.
  • tenet-compatibility: Incompatibility between released versions or with WPF for .NET Framework.

Milestones

We use milestones to prioritize work for each upcoming release.

• 3.0 milestone work is focused on parity with WPF for .NET Framework. We do not plan to take contributions or address issues that are not unique to WPF on .NET Core in 3.0 release. For example:
  • Bugs which are present on both WPF platforms (for .NET Core and .NET Framework) will be put into Future milestone and will be reviewed and prioritized after 3.0 final release.
  • Requests for new APIs and features will be put into Future milestone and will be reviewed and prioritized after 3.0 final release.
• Future milestone tracks all potential future work (which may or may not happen). When we are done with 3.0 release, we will move some of these issues into the next immediate milestone.
  • Please do not start discussions about next post-3.0 milestone until we are close to final 3.0 release. If you want to express your opinion on prioritization, please upvote first post of the issue instead.

Assignee

We assign each issue to assignee, when the assignee is ready to pick up the work and start working on it. If the issue is not assigned to anyone and you want to pick it up, please say so - we will assign the issue to you. If the issue is already assigned to someone, please coordinate with the assignee before you start working on it.

Prioritization & Upvoting

• Upvotes on first post of each issue are a useful hint for our prioritization. We can sort issues by number of upvotes and we will review the top list on regular basis.
• We're most likely to include improvements that either have a positive impact on a broad scenario or have very significant positive impact on a niche scenario. We're less likely to prioritize modest improvements to niche scenarios.
• Compatibility will almost always be given a higher priority than improvements.

Triage rules

Guidance for triaging issues for WPF team members:

1. Issue has no Assignee, unless someone is working on the issue at the moment.
2. Use up-for-grabs as much as possible, ideally with a quick note about next steps / complexity of the issue.
3. Set milestone to Future, unless you can 95%-commit you can fund the issue in specific milestone.
4. Each issue has exactly one "issue type" label (bug, enhancement, api-suggestion, test-bug, test-enhancement, question, documentation, etc.).
5. Don't be afraid to say no, or close issues - just explain why and be polite.
6. Don't be afraid to be wrong - just be flexible when new information appears.

Feel free to use other labels if it helps your triage efforts (e.g. needs-more-info, design-discussion, tenet-compatibility, etc.).

Motivation for triage rules

1. Issue has no Assignee, unless someone is working on the issue at the moment.
   • Motivation: Observation is that contributors are less likely to grab assigned issues, no matter what the repo rules say.
2. Use up-for-grabs as much as possible, ideally with a quick note about next steps / complexity of the issue.
   • Note: Per http://up-for-grabs.net, such issues should be no longer than few nights' worth of work. They should be actionable (i.e. no mysterious CI failures that can't be tested in the open).
3. Set milestone to Future, unless you can 95%-commit you can fund the issue in specific milestone.
   • Motivation: Helps communicate desire/timeline to community. Can spark further priority/impact discussion.
4. Each issue has exactly one "issue type" label (bug, enhancement, api-suggestion, test-bug, test-enhancement, question, documentation, etc.).
   • Don't be afraid to be wrong when deciding 'bug' vs. 'test-bug' (flip a coin if you must). The most useful values for tracking are 'api-*' vs. 'enhancement', 'question', and 'documentation'.
5. Don't be afraid to say no, or close issues - just explain why and be polite.
6. Don't be afraid to be wrong - just be flexible when new information appears.

PR guidance

Each PR has to have reviewer approval from at least one WPF team member who is not author of the change, before it can be merged.

1. Don't set any labels on PRs. They are superfluous and not needed (exceptions: NO MERGE).
   • Motivation: All the important info (issue type label, API approval label, etc.) is already captured on the associated issue.
2. Push PRs forward, don't let them go stale (response every 5+ days, ideally no PRs older than 2 weeks).
3. Close stuck or long-term blocked PRs (e.g. due to missing API approval, etc.) and reopen them once they are unstuck.
   • Motivation: Keep only active PRs. WIP (work-in-progress) PRs should be rare and should not become stale (2+ weeks old). If a PR is stale and there is not immediate path forward, consider closing the PR until it is unblocked/unstuck.
4. Link PR to related issue via auto-closing (add "Fixes #12345" into your PR description).