--- name: refresh-dotnet-versions description: Detect new .NET, C#, and F# releases and update all opinions and templates in this repository to target them, including the central NuGet package pins in templates/Directory.Packages.props and the GitHub Actions pins in opinion code blocks. Use when a new .NET SDK/runtime, C# language version, or F# version has shipped, when a pinned package or action has a newer stable release, or when asked to check whether the repository targets the latest released versions. license: See repository LICENSE compatibility: Requires git and internet access metadata: repo: awesome-humans/dotnet change-flow: branch-pr --- **Reading this without a checkout?** "This repository" in this skill means [`awesome-humans/dotnet`](https://github.com/awesome-humans/dotnet). A path such as `opinions/` or `templates/Directory.Build.props` is relative to its root. Read an opinion, template, skill, or the roster from its raw copy at `https://awesome-humans.net/dotnet/raw/none/`, with `.txt` added to a Markdown file's name and a template's leading dot dropped. For a house profile, follow the links in its `llms-.txt` instead. Any other file is at `https://raw.githubusercontent.com/awesome-humans/dotnet/main/`. A skill that changes the repository needs a checkout. # 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`. It's the cue to run this skill. - Never commit to `automation/dotnet-release-watch`. Until `main` has the new snapshot, each run of the workflow rebuilds that branch from `main` and force-pushes it, so a commit there is lost. - The skill works on its own branch, which step 3 starts, and copies the snapshot there. The refresh pull request then merges the snapshot and the update together, and step 8 closes the trigger pull request. - You can also run the skill by itself. The snapshot answers "Which GA versions does this repository know about?" offline. ## Orchestration As [agents/orchestration.md](https://raw.githubusercontent.com/awesome-humans/dotnet/main/agents/orchestration.md) 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 1. **Find the latest released versions.** - .NET: and the release announcement on the [.NET Blog](https://devblogs.microsoft.com/dotnet/). - C#: . - F#: . - Use GA releases only. A preview or release candidate can appear in a "Coming next" note, never as the target. 2. **Compare with the current targets:** the `targets:` metadata in `opinions/`, the version pins in `templates/`, and the root `global.json`. The template pins are the `global.json` SDK version, `` in project files, and `` 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. - If you stop here while a trigger pull request is open, check that its snapshot names the release step 1 found, and say that it can merge as it is. It holds only the snapshot, and nothing else lands it on `main`. If the snapshot names a newer release, run steps 1 and 2 again for that release. 3. **Start a worktree** from `main` on the branch `refresh/dotnet-`, following the rules in [agents/worktrees.md](https://raw.githubusercontent.com/awesome-humans/dotnet/main/agents/worktrees.md). - To find an open trigger pull request, run `gh pr list --label dotnet-release --state open`. A leftover `automation/dotnet-release-watch` branch without one isn't a trigger. - If one is open, copy its snapshot into the worktree: run `git fetch origin automation/dotnet-release-watch`, then `git restore --source=FETCH_HEAD -- .github/state/dotnet-releases.json`. Commit it with the rest of the run. - If that snapshot is older than the release step 1 found, run the workflow first, with `gh workflow run dotnet-release-watch.yml`, and copy the snapshot once it finishes. If it's newer, a release shipped after step 1 ran: run steps 1 and 2 again for that release. - Without a trigger pull request, leave the snapshot alone. Only the workflow writes it. The trigger pull request it opens later holds only the snapshot. It can merge as it is once the refresh pull request has merged, and not before: with the snapshot on `main` and no refresh, the workflow opens no further trigger for that release. 4. **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.json` files.** On a major release, move both to that major's first band, such as `11.0.100`. Between majors, leave `sdk.version` alone 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 `11.0.105` instead of `11.0.100`, 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, `scripts/` uses `#:include`, which needs SDK `10.0.300` or later, so the root `global.json` couldn't go below that band during .NET 10. - Between majors, the two files are independent. The root pin follows what `scripts/` needs, and the template pin follows what the example projects need. On a major release, the root moves with the template even when `scripts/` doesn't need it, so the repository's own checks run on the release its opinions target. Use `latestFeature` wherever the opinion says so. - `global.json` has no comment syntax, so the pinned value **is** the record. - Renovate never changes this field: `renovate.json` disables the `dotnet-sdk` dependency type, because a minimum under `latestFeature` doesn't need mechanical bumps. Only this skill changes it. - **4b. The package pins in `templates/Directory.Packages.props`.** Look up every `` on nuget.org, with the registration index (`https://api.nuget.org/v3/registration5-gz-semver2//index.json`) or `dotnet package search `. - 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 ` comment to the run date **whether or not any version changed**. It's the file's only freshness record. - **4c. The action pins in `opinions/` code blocks.** Find every `uses: /@ # ` line in a fenced code block under `opinions/`, such as the worked example in `opinions/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 / --json tagName`, then resolve the tag to its commit with `gh api repos///commits/ --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/checkout` and `actions/setup-dotnet` do, 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. 5. **Update each opinion** under `opinions/`: - Read the release's "What's new" pages from the first-party sources, `dotnet-blog` and `ms-learn`. Read detailed posts on each feature from the rest of the citable roster, such as `andrew-lock`'s "Exploring .NET" series. Read `stephen-toub`'s "Performance Improvements in .NET X" post for the release too, and check `opinions/runtime-performance.md` against it: delete any manual optimization that the runtime now does by itself. - 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 `TODO` and a source link, and add its `README.md` Scope bullet and Repository layout entry, which CI enforces. - Update `targets:` and `last-reviewed:` on every file you change **or verify as unchanged**. - **Never remove or weaken a house block or region** ([awesome-humans/website: House opinions](https://awesome-humans.net/raw/none/conventions/house-opinions.md.txt#how-this-works)). 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. 6. **If a .NET SDK is available, verify the code samples** against the new targets. Run **`just build-templates`**, which assembles the example projects from `templates/` and runs `dotnet build`, `dotnet test`, and `dotnet format --verify-no-changes` on them. The recipe checks only the templates. To check an opinion's sample, add it to a project's directory in the copy the recipe leaves in `artifacts/templates/none/`, such as `src/Example.Library/`, so that the project compiles it. A file at the root of the copy belongs to no project, and the build passes without it. Then run the same three commands there. - `dotnet run` calls the test project's entry point directly and skips the SDK's runner selection. It can pass where `dotnet test` fails, and `dotnet test` is what `templates/`, `opinions/ci.md`, and `audit-freshness` use. - 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. 7. **If the source roster changed, record it** in the `AWESOME-HUMANS.md` decision log. Otherwise, summarise the run in the pull request. 8. **Open a pull request** to the default branch, filling in the [`version-refresh.md`](https://github.com/awesome-humans/.github/blob/main/PULL_REQUEST_TEMPLATE/version-refresh.md) template, as [agents/maintaining.md](https://raw.githubusercontent.com/awesome-humans/dotnet/main/agents/maintaining.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. If the run copied a trigger pull request's snapshot, end the description with a `Refs: #` trailer for it, and comment on the trigger pull request with the refresh pull request's number. The comment says to close the trigger pull request once the refresh merges. After the refresh pull request merges, close the trigger pull request, if it's still open, with `gh pr close --delete-branch`. The workflow never closes it: once the snapshot on `main` matches the releases index, the workflow skips its pull request step. If the trigger pull request's snapshot differs from the one on `main` by then, a newer release has arrived. Leave it open as the cue for the next run. ## 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.props` is 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 for `vet-source` or 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`.