-
Notifications
You must be signed in to change notification settings - Fork 484
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
V3 setup-dotnet ADR #291
Merged
Merged
V3 setup-dotnet ADR #291
Changes from 3 commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,48 @@ | ||
| # V3 setup-dotnet | ||
|
|
||
| Date: 2022-08-25 | ||
| Status: Proposed | ||
|
|
||
| # Context | ||
| - GitHub-hosted Ubuntu and Windows runners have .NET versions pre-installed in system directories | ||
| - Ubuntu:`/usr/share/dotnet` | ||
| - Windows:`C:\Program Files\dotnet` | ||
| - V1 version of Action installs .NET to user's directory | ||
| - Ubuntu:`/home/runner/.dotnet` | ||
| - Windows: `C:\Users\runneradmin\AppData\Local\Microsoft\dotnet` | ||
| - It means that action always download and install .NET version even if it is pre-installed. Also after using the action all pre-installed .NET versions are unavailable because `DOTNET_ROOT` is overriden to user's directory. | ||
| The behavior is different for macOS runners because pre-installation directory matches the one that is used by action. It means action can use pre-installed versions if they exist, which speeds up customer's workflow. | ||
|
|
||
| - The different behavior of the setup task on Ubuntu, Windows and MacOS runners is unclear and confusing for customers. | ||
|
|
||
| - .NET supports installing and using multiple versions of .NET SDK and .NET runtime side-by-side. .NET CLI will use the latest installed .NET SDK and .NET runtime versions if there is no global.json file containing a different version. This behavior is defined by .NET design (https://docs.microsoft.com/en-us/dotnet/core/versions/selection). | ||
|
|
||
| - The action contains logic to handle inputs with wildcards, for example `5.0.x`, `5.0.*`, `5.x` or `5.*`. This logic uses metadata from `https://dotnetcli.blob.core.windows.net/dotnet/release-metadata/releases-index.json` to retrieve the list of available releases and get the latest release version for the specified major and/or minor version from input. After that, installer script (`dotnet-install.ps1` for Windows or `dotnet-install.sh` for Linux and MacOS) installs the required SDK using exact version as a parameter. | ||
|
|
||
| # Proposal | ||
| - Change .NET installation path for Windows and Ubuntu images to match the location of pre-installed versions by using `-InstallDir` (Windows) and `--install-dir` (Ubuntu) properties for installer scripts: | ||
| https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script | ||
| - Get rid of redundant logic to resolve wildcard version on the action side and start relying on [official installer scripts provided by .NET Core team](https://github.com/dotnet/install-scripts). | ||
| The execution `dotnet-install.ps1 -Channel 5.0` installs the latest patch version for 5.0 sdk. In this way we can handle inputs with wildcard as patch version (`5.0.x` or `5.0.*`) by passing major and minor version to installer script directly as `channel` parameter. This parameter supports two-part version in X.Y format as input values ([see installer scripts documentation](https://docs.microsoft.com/en-us/dotnet/core/tools/dotnet-install-script)). Furthermore, the version input format of action will follow the format which is supported by installers scripts. | ||
|
|
||
| # Breaking changes | ||
| - The presence of pre-installed .NET versions that are higher than version that the users specify in the setup task can be breaking for some customers, who expect only one installed .NET version on runner after using the setup task. If user doesn't have .NET version specified in project file, `dotnet` will use the latest installed version instead of provided in the setup task. | ||
| > **Note:** It is the biggest deal in this ADR. | ||
| Previously, when a user would specify a .NET version, this exact version was used by `dotnet` command by default (because it was installed in a separate folder and there were no other.NET versions in that folder) | ||
| In proposal, the specified version will be installed on machine but the latest version will be used by `dotnet` command by default (because specified version will be installed alongside with pre-installed .NET versions). | ||
| Based on [official .NET documentation](https://docs.microsoft.com/en-us/dotnet/core/versions/selection), it is expected behavior and how it works on user's local machine with multiple installed .NET versions but some customers could be broken because they already rely on current behavior. | ||
|
|
||
| - All possible inputs will continue to work as previously except `5.x`. It is totally okay to drop it because we shouldn't allow users to rely on such input. The new minor release of .NET will break their builds. | ||
|
|
||
| To avoid breaking customers, we will need to release a new major task version (V3). | ||
|
|
||
| # v3-preview | ||
| There will be a v3-preview branch that will be created for development and testing. Any changes will first be merged into v3-preview branch. After a period of testing & verification, the v3-preview branch will be merged into the main branch and a v3 tag will be created. Any GitHub public documentation and starter workflows that mention setup-dotnet will then be updated to use v3 instead of v2: | ||
| - [README.md](https://github.com/actions/setup-dotnet/blob/main/README.md) | ||
| - [action.yml](https://github.com/actions/setup-dotnet/blob/main/action.yml) | ||
| - [GitHub docs](https://docs.github.com/en/actions/guides/building-and-testing-net#using-a-specific-net-version) | ||
| - Starter-workflow yamls: [#1](https://github.com/actions/starter-workflows/blob/main/ci/dotnet.yml#L17), [#2](https://github.com/actions/starter-workflows/blob/main/ci/dotnet-desktop.yml#L72) | ||
|
|
||
| # Consequences | ||
| - Customers will be able to use pre-installed .NET versions with setup-dotnet action on Windows and Ubuntu | ||
| - Maintenance of the action will be easier due to the simplier logic of handling inputs with wildcards | ||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Is this a consequence of the above bullet point, or is it a separate issue?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@brcrista, it's a separate issue. Dotnet installer scripts can handle as parameter either full exact version or major.minor version. We're going to use only installer scripts functionality to resolve version without any additional http requests to dotnet releases list, so we are forced to remove an input version format like
5.x.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
So you can't say "give me the latest version of dotnet" anymore? That seems like a serious limitation. Do we know how many workflows would be broken by this change?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
About 4% of workflow runs with
setup-dotnetaction have this format (5.x, 6.x and etc) in the last month according Kusto.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Besides breaking those workflows, there's also a design issue. All the other
setup-actions accept the full syntax for SemVer version ranges. So excluding5.x, which is part of that syntax, is a bit confusing.Even though the code is more complicated, the user experience is paramount. It would be better to continue to look up the latest minor version as we have been. I think wanting to install the latest version of .NET is a perfectly legitimate use case and one we should continue to support.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@brcrista, I see. Since we can't implement this logic without some damage for customers I removed the part of ADR about it.