issue-guide.md

Issue Guide

This page outlines how the CoreFx 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. However, it should be work that falls under the charter of CoreFx, which is a collection of foundational libraries that make up the .NET Core development stack. We will keep issues open even if the CoreFx team internally has no plans to address them in an upcoming release, as long as we consider the issue to fall under our purview.

When we close issues

As noted above, we don't close issues just because we don't plan to address them in an upcoming release. So why do we close issues? There are few major reasons:

1. Issues unrelated to CoreFx. When possible, we'll try to find a better home for the issue and point you to it.
2. Cross cutting work better suited for another team. Sometimes the line between the framework, languages and runtime blurs. For some issues, we may feel that the work is better suited for the runtime team, language team or other partner. In these cases, we'll close the issue and open it with the partner team. If they end up not deciding to take on the issue, we can reconsider it here.
3. Nebulous and Large open issues. Large open issues are sometimes better suited for User Voice, especially when the work will cross the boundaries of the framework, language and runtime. A good example of this is the SIMD support we recently added to CoreFx. This started as a User Voice request, and eventually turned into work for both the core libraries and runtime.

Sometimes after debate, we'll decide an issue isn't a good fit for CoreFx. In that case, we'll also close it. Because of this, we ask that you don't start working on an issue until it's tagged with up for grabs or api-approved. Both you and the team will be unhappy if you spend time and effort working on a change we'll ultimately be unable to take. We try to avoid that.

Labels

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

• Area: These area-* labels (e.g. area-System.Collections) call out the assembly or assemblies the issue applies to. In addition to labels per assembly, we have a few other area labels: area-Infrastructure, for issues that relate to our build or test infrastructure, and area-Meta for issues that deal with the repository itself, the direction of the .NET Core Platform, our processes, etc. See full list of areas.
• Issue Type: These labels classify the type of issue. We use the following types:
• bug: Bugs in an assembly.
• api-* (api-approved, api-needs-work): Issues which would add APIs to an assembly (see API Review process for details).
• enhancement: Improvements to an assembly which do not add new APIs (e.g. performance improvements, code cleanup).
• test bug: Bugs in the tests for a specific assembly.
• test enhancement: Improvements in the tests for a specific assembly (e.g. improving test coverage).
• documentation: Issues related to documentation (e.g. incorrect documentation, enhancement requests).
• question: Questions about the product, source code, etc.
• Other:
• up for grabs: Small 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.

In addition to the above, we have a handful of other labels we use to help classify our issues. Some of these tag cross cutting concerns (e.g. tenet-performance), whereas others are used to help us track additional work needed before closing an issue (e.g. api-needs-exposed).

Milestones

We use milestones to prioritize work for each upcoming release to NuGet.org.

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.

Note: This is a new scheme introduced in 2016/9. The old scheme used assignees as area owners. We will migrate issues to the new scheme throughout 2016.

Areas

Areas are tracked by labels area-* (e.g. area-System.Collections). Each area typically corresponds to one or more contract assemblies.

Area	Owners / experts	Description
area-Infrastructure	@mellinoe, @ericstj, @weshaggard	Covers: Packaging Build and test infra VS intergation Triage in progress
area-Meta	@tarekgh	Issues without clear association to any specific API/contract, e.g. new contract proposals cross-cutting code/test pattern changes (e.g. FxCop failures) project-wide docs Triage in progress
area-Serialization	@shmao, @zhenlan	Packages: System.Runtime.Serialization.Xml System.Runtime.Serialization.Json System.Private.DataContractSerialization System.Xml.XmlSerialization Excluded: System.Runtime.Serialization.Formatters
System contract assemblies
System.AppContext	@AlexGhiondea
System.Buffers	@alexperovich, @safern
System.CodeDom	@Priya91
System.Collections	@Priya91, @ianhays
System.ComponentModel	@safern, @AlexGhiondea
System.ComponentModel.DataAnnotations	@lajones, @divega	Pending triage
System.Composition	@AlexGhiondea
System.Console	@ianhays
System.Data	@saurabh500, @YoungGah
System.Data.SqlClient	@saurabh500, @YoungGah	Pending triage
System.Diagnostics	@joperezr
System.Diagnostics.Process	@Priya91	Pending triage
System.Diagnostics.Tracing		Pending triage
System.DirectoryServices	@tquerec
System.Drawing	@alexperovich
System.Dynamic.Runtime	@VSadov, @OmarTawfik
System.Globalization	@krwq, @tarekgh
System.IO	@JeremyKhune, @ianhays
System.IO.Compression	@ianhays
System.Linq	@VSadov, @OmarTawfik
System.Linq.Expressions	@VSadov, @OmarTawfik	Pending triage
System.Linq.Parallel	@alexperovich, @kouvel
System.Net		Pending triage
System.Numerics	@mellinoe
System.Reflection		Pending triage
System.Reflection.Emit		Pending triage
System.Reflection.Metadata	@tmat, @nguerrera
System.Resources	@ramarag, @tarekgh	Pending triage
System.Runtime	@AlexGhiondea, @joperezr	Included: System.Runtime.Serialization.Formatters System.Runtime.InteropServices.RuntimeInfo Excluded: Path -> System.IO StopWatch -> System.Diagnostics WebUtility -> System.Net Triage in progress
System.Runtime.CompilerServices	@AlexGhiondea, @joperezr
System.Runtime.Extensions	@AlexGhiondea, @joperezr	Pending triage
System.Runtime.InteropServices	@tijoytom, @yizhang82	Excluded: System.Runtime.InteropServices.RuntimeInfo
System.Security	@bartonjs, @steveharter	Triage in progress
System.ServiceModel	N/A	dotnet/wcf
System.ServiceProcess	@Priya91
System.Text.Encoding	@krwq, @tarekgh
System.Text.RegularExpressions	@Priya91	Pending triage
System.Threading	@kouvel, @alexperovich
System.Transactions	@jimcarley, @qizhanMS, @dmetzgar
System.Xml	@sepidehMS, @krwq
Microsoft contract assemblies
Microsoft.CSharp	@VSadov, @OmarTawfik
Microsoft.VisualBasic	@VSadov, @OmarTawfik
Microsoft.Win32	@sepidehMS

Note: Area triage will apply the new scheme (issue types and assignee) throughout 2016.

Triage rules - simplified

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