Updates to release planning

Specifically added text about how to read the backlog and the process for deciding what to patch.

Author: ajcvickers

entity-framework/core/what-is-new/index.md

@@ -1,7 +1,7 @@
 ---
 title: EF Core releases and planning
 author: ajcvickers
-ms.date: 01/14/2020
+ms.date: 01/29/2020
 ms.assetid: C21F89EE-FB08-4ED9-A2A0-76CB7656E6E4
 uid: core/what-is-new/index
 ---
@@ -30,18 +30,32 @@ See the [.NET support policy](https://dotnet.microsoft.com/platform/support/poli
 * Major version updates (for example, from EF Core 2 to EF Core 3) often have breaking changes. Thorough testing is advised when updating across major versions. Use the breaking changes links above for guidance on dealing with breaking changes.
 * Minor version updates do not typically contain breaking changes. However, thorough testing is still advised since new features can introduce regressions.
 
+## Release planning and schedules
+
+EF Core releases align with the [.NET Core shipping schedule](https://github.com/dotnet/core/blob/master/roadmap.md).
+
+Patch releases usually ship monthly, but have a long lead time.
+We are working to improve this.
+
+See the [release planning process](release-planning.md) for more information on how we decide what to ship in each release.
+We typically don't do detailed planning for further out than the next major or minor release.
+
 ## EF Core 5.0
 
-EF Core releases align with the [.NET Core shipping schedule](https://github.com/dotnet/core/blob/master/roadmap.md). The next planned stable release is **EF Core 5.0**, scheduled for November 2020.
+The next planned stable release is **EF Core 5.0**, scheduled for November 2020.
 
 A [high-level plan for EF Core 5.0](ef-core-5.0/plan.md) has been created by following the documented [release planning process](release-planning.md).
 
-Your feedback on planning is important. The best way to indicate the importance of an issue is to vote (thumbs-up) for that issue on GitHub. This data will then feed into the planning process for the next release.
+Your feedback on planning is important.
+The best way to indicate the importance of an issue is to vote (thumbs-up 👍) for that issue on GitHub.
+This data will then feed into the planning process for the next release.
 
 ### Get it now!
 
 EF Core 5.0 packages are **available now** as [daily builds](https://github.com/aspnet/AspNetCore/blob/master/docs/DailyBuilds.md). 
 
-Using the daily builds is a great way to find issues and provide feedback as early as possible. The sooner we get such feedback, the more likely it will be actionable before the next official release. We work hard to keep the daily builds in good shape by running over 55,000 tests per platform for each build.
+Using the daily builds is a great way to find issues and provide feedback as early as possible.
+The sooner we get such feedback, the more likely it will be actionable before the next official release.
+We work hard to keep the daily builds in good shape by running over 56,000 tests per platform for each build.
 
 Preview packages will be shipped to NuGet later in the year.

entity-framework/core/what-is-new/release-planning.md

@@ -1,45 +1,122 @@
 ---
 title: EF Core release planning
 author: ajcvickers
-ms.date: 01/14/2020
+ms.date: 01/28/2020
 uid: core/what-is-new/release_planning.md
 ---
 
 # Release planning process
 
 We often get questions about how we choose specific features to go into a particular release.
-Our backlog certainly doesn't automatically translate into release plans.
-The presence of a feature in EF6 also doesn't automatically mean that the feature needs to be implemented in EF Core.
+This document outlines the process we use.
+The process is continually evolving as we find better ways to plan, but the general ideas remain the same.
 
-It's difficult to detail the whole process we follow to plan a release.
-Much of it is discussing the specific features, opportunities and priorities, and the process itself also evolves with every release.
-However, we can summarize the common questions we try to answer when deciding what to work on next:
+## Different kinds of releases
 
-1. **How many developers we think will use the feature and how much better will it make their applications or experience?** To answer this question, we collect feedback from many sources — Comments and votes on issues is one of those sources.
+Different kinds of release contain different kinds of changes.
+This in turn means that the release planning is different for different kinds of release.
 
-2. **What are the workarounds people can use if we don't implement this feature yet?** For example, many developers can map a join table to work around lack of native many-to-many support. Obviously, not all developers want to do it, but many can, and that counts as a factor in our decision.
+### Patch releases
 
-3. **Does implementing this feature evolve the architecture of EF Core such that it moves us closer to implementing other features?** We tend to favor features that act as building blocks for other features. For instance, property bag entities can help us move towards many-to-many support, and entity constructors enabled our lazy loading support.
+Patch releases change only the "patch" part of the version.
+For example, EF Core 3.1.**1** is a release that patches issues found in EF Core 3.1.**0**.
 
-4. **Is the feature an extensibility point?** We tend to favor extensibility points over normal features because they enable developers to hook their own behaviors and compensate for any missing functionality.
+Patch releases are intended to fix critical customer bugs.
+This means patch releases do not include new features.
+API changes are not allowed in patch releases except in special circumstances.
 
-5. **What is the synergy of the feature when used in combination with other products?** We favor features that enable or significantly improve the experience of using EF Core with other products, such as .NET Core, the latest version of Visual Studio, Microsoft Azure, and so on.
+The bar to make a change in a patch release is very high.
+This is because it is critical that patch releases do not introduce new bugs.
+Therefore, the decision process emphasizes high value and low risk.
+
+We are more likely to patch an issue if:
+  * It is impacting multiple customers
+  * It is a regression from a previous release
+  * The failure causes data corruption
+
+We are less likely to patch an issue if:
+  * There are reasonable workarounds
+  * The fix has high risk of breaking something else
+  * The bug is in a corner-case
+
+This bar gradually rises through the lifetime of a [long-term support (LTS)](https://dotnet.microsoft.com/platform/support/policy/dotnet-core) release. This is because LTS releases emphasize stability.
+
+The final decision about whether or not to patch an issue is made by the .NET Directors at Microsoft.
+
+### Minor releases
+
+Minor releases change only the "minor" part of the version.
+For example, EF Core 3.**1**.0 is a release that improves on EF Core 3.**0**.0.
+
+Minor releases:
+* Are intended to improve the quality and features of the previous release
+* Typically contain bug fixes and new features
+* Do not include intentional breaking changes
+* Have a few prerelease previews pushed to NuGet
+
+### Major releases
+
+Major releases change the EF "major" version number.
+For example, EF Core **3**.0.0 is a major release that makes a big step forward over EF Core 2.2.x.
+
+Major releases:
+* Are intended to improve the quality and features of the previous release
+* Typically contain bug fixes and new features
+  * Some of the new features may be fundamental changes to the way EF Core works
+* Typically include intentional breaking changes
+  * Breaking changes are necessary part of evolving EF Core as we learn
+  * However, we think very carefully about making any breaking change because of the potential customer impact. We may have been too aggressive with breaking changes in the past. Going forward, we will strive to minimize changes that break applications, and to reduce changes that break database providers and extensions.
+* Have many prerelease previews pushed to NuGet
 
-6. **What are the skills of the people available to work on a feature, and how to best leverage these resources?** Each member of the EF team and our community contributors has different levels of experience in different areas, so we have to plan accordingly. Even if we wanted to have "all hands on deck" to work on a specific feature like GroupBy translations, or many-to-many, that wouldn't be practical.
+## Planning for major/minor releases
 
-As mentioned before, the process evolves on every release.
-In the future, we'll try to add more opportunities for members of the community to provide inputs into our release plans.
-For example, we would like to make it easier to review draft designs of the features and of the release plan itself.
+### GitHub issue tracking
 
-## Backlog
+GitHub ([https://github.com/dotnet/efcore](https://github.com/dotnet/efcore)) is the source-of-truth for all EF Core planning.
 
-The [Backlog Milestone](https://github.com/aspnet/EntityFrameworkCore/issues?q=is%3Aopen+is%3Aissue+milestone%3ABacklog+sort%3Areactions-%2B1-desc) in our issue tracker contains issues that we either expect to work on someday, or we think someone from the community could tackle.
-Customers are welcome to submit comments and votes on these issues.
-Contributors looking to work on any of these issues are encouraged to first start a discussion on how to approach them.
+Issues on GitHub have:
 
-There's never a guarantee that we'll work on any given feature in a specific version of EF Core.
-As in all software projects, priorities, release schedules, and available resources can change at any point.
-But if we intend to resolve an issue in a specific time-frame, we'll assign it to a release milestone instead of the backlog milestone.
+* A state
+  * [Open](https://github.com/dotnet/efcore/issues) issues have not been addressed.
+  * [Closed](https://github.com/dotnet/efcore/issues?q=is%3Aissue+is%3Aclosed) issues have been addressed.
+    * All issues that have been fixed are [tagged with closed-fixed](https://github.com/dotnet/efcore/issues?q=is%3Aissue+label%3Aclosed-fixed+is%3Aclosed). An issue tagged with closed-fixed is fixed and merged, but may not have been released.
+    * Other `closed-` labels indicate other reasons for closing an issue. For example, duplicates are tagged with closed-duplicate.
+* A type
+  * [Bugs](https://github.com/dotnet/efcore/issues?q=is%3Aissue+is%3Aopen+label%3Atype-bug) represent bugs.
+  * [Enhancements](https://github.com/dotnet/efcore/issues?q=is%3Aissue+is%3Aopen+label%3Atype-enhancement) represent new features or better functionality in existing features.
+* A milestone
+  * [Issues with no milestone](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+no%3Amilestone) are being considered by the team. The decision on what to do with the issue has not yet been made or a change in the decision is being considered.
+  * [Issues in the Backlog milestone](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+milestone%3ABacklog) are items that the EF team will consider working on in a future release
+    * Issues in the backlog may be [tagged with consider-for-next-release](https://github.com/dotnet/efcore/issues?q=is%3Aissue+is%3Aopen+label%3Aconsider-for-next-release) indicating that this work item is high on the list for the next release.
+  * Open issues in a versioned milestone are items that the team plans to work on in that version. For example, [these are the issues we plan to work on for EF Core 5.0](https://github.com/dotnet/efcore/issues?q=is%3Aopen+is%3Aissue+milestone%3A5.0.0).
+  * Closed issues in a versioned milestone are issues that are completed for that version. Note that the version may not yet have been released. For example, [these are the issues completed for EF Core 3.0](https://github.com/dotnet/efcore/issues?q=is%3Aissue+milestone%3A3.0.0+is%3Aclosed).
+* Votes!
+  * Voting is the best way to indicate that an issue is important to you.
+  * To vote, just add a "thumbs-up" 👍 to the issue. For example, [these are the top-voted issues](https://github.com/dotnet/efcore/issues?q=is%3Aissue+is%3Aopen+sort%3Areactions-%2B1-desc)
+  * Please also comment describing specific reasons you need the feature if you feel this adds value. Commenting "+1" or similar does not add value.
+
+### The planning process
+
+The planning process is more involved than just taking the top-most requested features from the backlog.
+This is because we gather feedback from multiple stakeholders in multiple ways.
+We then shape a release based on:
+
+* Input from customers
+* Input from other stakeholders
+* Strategic direction
+* Resources available
+* Schedule
+
+Some of the questions we ask are:
+
+1. **How many developers we think will use the feature and how much better will it make their applications or experience?** To answer this question, we collect feedback from many sources — Comments and votes on issues is one of those sources. Specific engagements with important customers is another.
+
+2. **What are the workarounds people can use if we don't implement this feature yet?** For example, many developers can map a join table to work around lack of native many-to-many support. Obviously, not all developers want to do it, but many can, and that counts as a factor in our decision.
+
+3. **Does implementing this feature evolve the architecture of EF Core such that it moves us closer to implementing other features?** We tend to favor features that act as building blocks for other features. For instance, property bag entities can help us move towards many-to-many support, and entity constructors enabled our lazy loading support.
+
+4. **Is the feature an extensibility point?** We tend to favor extensibility points over normal features because they enable developers to hook their own behaviors and compensate for any missing functionality.
+
+5. **What is the synergy of the feature when used in combination with other products?** We favor features that enable or significantly improve the experience of using EF Core with other products, such as .NET Core, the latest version of Visual Studio, Microsoft Azure, and so on.
 
-We'll likely close an issue if we don't plan to ever address it.
-But we can reconsider an issue that we previously closed if we get new information about it.
+6. **What are the skills of the people available to work on a feature, and how can we best leverage these resources?** Each member of the EF team and our community contributors has different levels of experience in different areas, so we have to plan accordingly. Even if we wanted to have "all hands on deck" to work on a specific feature like GroupBy translations, or many-to-many, that wouldn't be practical.

entity-framework/toc.yml

@@ -21,7 +21,7 @@
       href: core/index.md
     - name: "Releases and planning"
       items:
-      - name: Current and planned releases
+      - name: Current and planned releases (Roadmap)
         href: core/what-is-new/index.md
       - name: Release planning process
         href: core/what-is-new/release-planning.md