SDK PR Guide

Branching & Release Schedules

See the versions document for more details on how SDK versions map to MSBuild and Visual Studio. The Visual Studio schedule is available on the devdiv internal Azure DevOps wiki and the .NET schedule is communicated through the internal .NET Tactics alias.

Major releases

The .NET SDK has yearly major releases aligning with the .NET Runtime in November. These releases will be of the form N.0.1xx. The feature work for major releases will be done in main.

Typically, previews for each major release start in February of each year. For each preview, we will snap a new branch off of main approximately midway through the prior month.

During .NET 7, for example, the preview branches were created around the 21st of each month prior, with the later previews forking earlier to provide more time for stabilization and codeflow. The main branch's major version will be set to match the next year's major release in August. (For example, the switch from .NET 7 to .NET 8 occurred in August of 2022, while .NET 8 was set for release in 2023.) Warning: This process can take a bit for those waiting to develop features for the next major release. In prior releases it has taken 1-3 months before the new branch could be fully used to target the new .NET Runtime version.

Minor releases

The .NET SDK has quarterly minor releases that align with Visual Studio releases. For example, two different quarterly releases in the same schedule would be: 7.0.200 vs 7.0.300. These SDK releases are open to all bug fixes and some features work as well. These quarterly releases should avoid breaking changes if at all possible. Breaking changes instead should be included in the major releases and be tied to customer TargetFramework updates when possible. We do this to limit the pain of breaking changes, as customers need to take action (upgrading the TargetFramework) before they are broken.

Minor releases lock down after preview 3 for each release. Preview 3 is typically 1 month prior to GA and locks down by the end of the month before the preview release.

Transition from minor release to servicing

After the minor release locks down, it transitions into servicing / "QB" (Quarterback) mode. This typically happens around the preview 3 release to allow time for any late public changes we want feedback on. The next release after preview 3 is typically GA and done as a servicing release. The following steps are done when transitioning from minor release previews to servicing:

Follow the new branch check list for creating a new minor release (steps listed on internal OneNote)
Set StabilizePackageVersion to true
Enable internal runtime darc subscriptions and trigger them

Servicing releases

The .NET SDK has monthly servicing releases (e.g.7.0.100 VS 7.0.101) aligning with the .NET Runtime servicing releases. These are for top fixes and security updates only to limit risk. Any servicing release is open for check-ins from the day the branding PRs are merged (~1st Tuesday of each month) and when code complete is (typically two weeks later). The servicing branches are locked from the time of code complete to the next branding in case we need to respin any monthly release. We use the Branch Lockdown label to mark PRs that should go into the next servicing release but the branch is currently not open. Final signoffs are typically in the last week of each month. We have a workflow that will automatically mark any PR targeting a servicing branch outside of the first to third Tuesday window: https://github.com/dotnet/sdk/blob/main/.github/workflows/add-lockdown-label.yml

Schedule

Release Type	Frequency	Lockdown Release	Branch Open	Lockdown Date (estimate)
Major	Yearly (Nov)	RC2	~August	Mid-September
Minor	Quarterly	Preview 3	~Prior release Preview 3 date	End of the month prior to Preview 3 (~7 weeks prior to release)
Servicing	Monthly	N/A	After branding, ~1st Tuesday of the prior month	Third Tuesday of prior month (signoff is ~28th of each month)

Tactics approval

Even releases that are in lockdown can still take changes as long as they are approved and the final build isn't complete. To bring a change through tactics, mark it with the label servicing-consider and update the description to include 5 sections (Description, Customer Impact, Regression?, Risk, Testing). See previously approved bugs for examples by looking for the servicing-approved label.

For servicing changes to other repos like MSBuild and NuGet, we recommend getting approval from tactics before the PR is merged. For codeflow, we do not gate codeflow on approvals as many codeflows are just infra work that doesn't require approval. Separating those out would add additional complexity we want to avoid.

External contributions

External contributions are encouraged and welcome. There are so many teams working in this repo that it can be hard to track. Contributors looking to learn more about how to contribute should check out the Developer Guide.

Ping @dotnet/domestic-cat when ready for a review
Make sure all tests and checks are passing
Make sure to add a new test for the scenario (when it makes sense)

Triage and PR review meetings are Wednesdays each week. If your PR is passing checks and has been reviewed by then, that's when we typically merge.

Codeflow

Codeflow is handled by darc. Codeflow comes from three runtime branches and a dozen tools branches. @dotnet/domestic-cat will monitor codeflow and approve passing PRs (as all PRs require 1 approver) and ping the owning team for any failures.

Internal Builds

The .NET SDK Installer is what allows the .NET SDK to be installed on a machine for usage in a proper developer environment, rather than for developing the .NET SDK itself. The installer has nightly builds that align with the .NET SDK which you can find here. The number of the build may be of particular interest. The build numbers match the internal build numbers with some caveats. YYYY MM DD are squashed to 5 digits. The first 2 digits represent the final 2 digits of the year. The next 3 digits represent the month and year: 50*The_Month_Number + the day of the month. The final suffix after the decimal value is the number of the build for that given day.

Example: 23080.2 is 2023, January 30th (1*50) + 30, and the second internal build of the SDK for that day.

Internal Branching

All monthly servicing releases are done of our internal branches in case there are security changes that have to go out. That means all flows from runtime branches into the SDK and from SDK to installer are done internally. That is why we have removed all servicing builds from the installer main page as those builds do not include any changes from any repo other than the installer repo so are very limited. Internal codeflow is merged into public GitHub repos on patch Tuesday each month to ensure we are updated.

Inter-branch codeflow

In the SDK repo, we have automated codeflow set up for each non-preview release branch flowing from the oldest branch all the way to main. You can see the configuration for that in github-merge-flow.jsonc. The workflow configuration is in inter-branch-merge-flow.yml You can see the existing open branch codeflows here

Further updates

These PRs will not get updated as new changes come in. This allows time to run PR checks, review, and merge. Once the existing PR is merged and all changes since that PR was created will be generated in a new PR. This leads to failed workflow automation but that's expected. The workflow will report this message: hint: Updates were rejected because the tip of your current branch is behind.

Reviewing and merging inter-branch codeflow

Generally we will check the commit list and scan the changes for anything out of the ordinary. We take a special look for any conflict merges that were done in getting the PR building.

Important

Make sure to create a merge commit. Do not squash. If you squash, the next inter-branch PR will list all of the same commits.

NOTE Some inter-branch flow will have 0 changes once the merge conflicts are resolved. This is likely when the only changes were to version numbers in the eng/*. These can be closed to save time and resources or merged to catch the commit history up (the next codeflow will have fewer commits). There is no preference either way.