Refresh .NET versions
Move every resource to the latest released (GA) versions of .NET, C#, and F#, and every package pin in templates/Directory.Packages.props and every action pin in an opinions/ code block to its latest stable version.
Trigger
The .github/workflows/dotnet-release-watch.yml workflow checks the official releases index daily. When the GA state changes, it opens a trigger pull request labelled dotnet-release on the branch automation/dotnet-release-watch.
- The trigger pull request only updates the snapshot in
.github/state/dotnet-releases.json. - Run this skill on that branch to make the update, and merge both together.
- You can also run the skill by itself. The snapshot answers "Which GA versions does this repository know about?" offline.
Orchestration
As AGENTS.md: Orchestration and model economy describes, delegate the web lookups to worker agents: the version checks in step 1, the nuget.org lookups in step 4b, the action release lookups in step 4c, and the "What's new" reading in step 5. Only the editor decides what changes, and edits opinions/ and templates/.
Steps
- Find the latest released versions.
- .NET: https://dotnet.microsoft.com/download/dotnet and the release announcement on the .NET Blog.
- C#: https://learn.microsoft.com/dotnet/csharp/whats-new/.
- F#: https://learn.microsoft.com/dotnet/fsharp/whats-new/.
- Use GA releases only. A preview or release candidate can appear in a "coming next" note, never as the target.
- Compare with the current targets: the
targets:metadata inopinions/, the version pins intemplates/, and the rootglobal.json. The template pins are theglobal.jsonSDK version,<TargetFramework>in project files, and<LangVersion>if it's pinned.- If everything matches, the framework part has nothing to do. Say so, and still run steps 4b and 4c, because package and action pins drift on their own schedule. Check step 4a for a band the repository now needs.
- Report "up to date" and stop only when those checks find nothing too.
- Start a worktree on the branch
refresh/dotnet-<version>, following the rules in AGENTS.md. -
Update the template files under
templates/: the TFMs in the example projects, and anything else pinned to a version. Then update the three kinds of pin that drift independently of a .NET release:- 4a. The SDK minimum in both
global.jsonfiles. Leavesdk.versionalone unless the repository needs something from a newer feature band.- The value is a minimum. With
"rollForward": "latestFeature", it accepts that version or any later band and patch on the machine, so new bands arrive without an edit. - Raising the minimum only narrows who can build. Pinning a patch, such as
10.0.412instead of10.0.400, fails contributors one servicing release behind. - When a band ships something the repository uses, raise the minimum, and give the reason in the pull request. For example, the root
global.jsonis at10.0.400because that's the first band that supports#:include. - The two files are independent. The root pin follows what
scripts/needs, and the template pin follows what the example projects need. UselatestFeaturewherever the opinion says so. global.jsoncan't carry a comment header, so the pinned value is the record.- Renovate never changes this field:
renovate.jsondisables thedotnet-sdkdependency type, because a minimum underlatestFeaturedoesn't need mechanical bumps. Only this skill changes it.
- The value is a minimum. With
- 4b. The package pins in
templates/Directory.Packages.props. Look up every<PackageVersion>on nuget.org, with the registration index (https://api.nuget.org/v3/registration5-gz-semver2/<lowercased-id>/index.json) ordotnet package search <id>.- Take the latest stable version. Never take a prerelease, or a version whose TFM support falls below
targets:. - Before you take a new major version, read its release notes. A major version that changes an idiom an opinion teaches is a content change: handle it in step 5.
- Set the
Versions verified against nuget.org … on <date>comment to the run date whether or not any version changed. It's the file's only freshness record.
- Take the latest stable version. Never take a prerelease, or a version whose TFM support falls below
- 4c. The action pins in
opinions/code blocks. Find everyuses: <owner>/<repo>@<sha> # <version>line in a fenced code block underopinions/, such as the worked example inopinions/ci.md.- Renovate doesn't update a SHA inside Markdown, and a pinned SHA never reports that it's out of date. Readers copy these examples, so this step is the only thing that keeps them current.
- Look up the action's latest stable release with
gh release view --repo <owner>/<repo> --json tagName, then resolve the tag to its commit withgh api repos/<owner>/<repo>/commits/<tag> --jq .sha. Don't take the SHA of an annotated tag object:uses:needs the commit. - Replace the SHA, and set the trailing comment to the release's full version, such as
# v7.0.2. - When an action also runs in this repository's own workflows, as
actions/checkoutandactions/setup-dotnetdo, match the pin in.github/workflows/. Renovate keeps those current, and the opinion says the repository runs them, so the two must agree. - Before you take a new major version, read its release notes. An input, output, or default that the example relies on might have changed. Fix the example in the same edit, and say what changed in the pull request.
- 4a. The SDK minimum in both
-
Update each opinion under
opinions/:- Read the release's "What's new" pages from the first-party sources,
dotnet-blogandms-learn. Read feature deep dives from the rest of the citable roster, such asandrew-lock's "Exploring .NET" series. - Add a new language or runtime feature where it changes an opinion, for example a new syntax that replaces an old idiom.
- When a feature needs a new opinion, create a stub with a
TODOand a source link, and add itsREADME.mdScope bullet and Repository layout entry, which CI enforces. - Update
targets:andlast-reviewed:on every file you change or verify as unchanged. - Never remove or weaken a house block or region (awesome-humans/website: House opinions). If a release makes one obsolete, note inside the block that the release supersedes it, and keep the marking. A template must still build with its house regions removed.
- Read the release's "What's new" pages from the first-party sources,
- If a .NET SDK is available, verify the code samples against the new targets. Assemble a scratch project from
templates/, and rundotnet build,dotnet test, anddotnet format --verify-no-changes.dotnet runcalls the test project's entry point directly and skips the SDK's runner selection. It can pass wheredotnet testfails, anddotnet testis whattemplates/,opinions/ci.md, andaudit-freshnessuse.- Treat "0 tests ran, exit code 0" as a failure. It's what a test project reports after losing its runner configuration.
- Without an SDK, flag the samples as unverified in the pull request.
- If the source roster changed, record it in the
AWESOME-HUMANS.mddecision log. Otherwise, summarise the run in the pull request. -
Open a pull request to the default branch, filling in the
version-refresh.mdtemplate, as AGENTS.md describes. It lists:- The versions before and after: the framework, the SDK band, each package pin, and each action pin that changed.
- The opinions that changed, and the ones verified as unchanged.
- Whether the samples built and tested.
- Anything left as a TODO.
A person reviews it before it changes any opinion.
Edge cases
- Release timing: A new major .NET version ships every November, with a new C# version. Mid-year releases are servicing releases. They don't change the framework targets, and rarely step 4a, because a new band alone isn't a reason to raise the minimum. A mid-year run that only changes
Directory.Packages.propsis normal. - An unmaintained package: If a package's latest stable release is much older than the current
targets:, the library is probably unmaintained. Leave the pin, and raise it forvet-sourceor opinion review. - Guidance lags the runtime: If a feature is GA but the vetted sources haven't covered it, update the target, and keep the old idiom with a note. Don't write unsourced guidance.
- STS or LTS: Target the latest release on either track. Note its end of support in
opinions/project-structure.md.