-
Notifications
You must be signed in to change notification settings - Fork 6k
Add examples to roll-forward table #46238
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
base: main
Are you sure you want to change the base?
Conversation
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.
Thank you for this submission! I've included some suggestions. @richlander can you validate how .NET roll forward currently works?
includes/roll-forward-table.md
Outdated
|
||
For example, suppose an application requests version `8.0.0`, while the locally available versions are `8.2.0`, `8.2.3`, `8.4.5`, `9.0.0`, `9.0.6`, `9.7.8`. | ||
Then the resolved version is as follows in each case: | ||
|
||
| Value | Resolved version | Resolved version if `8.0.1` were also available | | ||
|---------------|------------------|-------------------------------------------------| | ||
| `Minor` | `8.2.3` | `8.0.1` | | ||
| `Major` | `8.2.3` | `8.0.1` | | ||
| `LatestPatch` | (fails) | `8.0.1` | | ||
| `LatestMinor` | `8.4.5` | `8.4.5` | | ||
| `LatestMajor` | `9.7.8` | `9.7.8` | | ||
| `Disable` | (fails) | (fails) | | ||
|
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.
I don't think this should be here as this is an include file that only has a single table. The extra context would be provided by the actual article that uses this include file, if appropriate.
For example, suppose an application requests version `8.0.0`, while the locally available versions are `8.2.0`, `8.2.3`, `8.4.5`, `9.0.0`, `9.0.6`, `9.7.8`. | |
Then the resolved version is as follows in each case: | |
| Value | Resolved version | Resolved version if `8.0.1` were also available | | |
|---------------|------------------|-------------------------------------------------| | |
| `Minor` | `8.2.3` | `8.0.1` | | |
| `Major` | `8.2.3` | `8.0.1` | | |
| `LatestPatch` | (fails) | `8.0.1` | | |
| `LatestMinor` | `8.4.5` | `8.4.5` | | |
| `LatestMajor` | `9.7.8` | `9.7.8` | | |
| `Disable` | (fails) | (fails) | |
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.
Oh good point; I'll move it to
docs/docs/core/versions/selection.md
Line 160 in 58615fb
[!INCLUDE [roll-forward-table](../../../includes/roll-forward-table.md)] |
includes/roll-forward-table.md
Outdated
| `LatestPatch` | Roll-forward to the highest patch version. This value disables minor version roll-forward. | | ||
| `LatestMinor` | Roll-forward to highest minor version, even if requested minor version is present. | | ||
| `LatestMajor` | Roll-forward to highest major and highest minor version, even if requested major is present. | | ||
| `Minor` | **Default** if not specified.<br>Roll-forward to the lowest higher minor version (and highest available patch version within that minor version), if requested minor version is missing. If the requested minor version is present, then the `LatestPatch` policy is used. | |
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.
Even though I wrote this years ago, it took me quite a while to decipher what "lowest higher minor version" actually is. I wonder if using something like next available minor version
or first higher available minor
is clearer? I'm not sure though.. thoughts?
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.
As a first pass, I've gone with "next available", which matches the wording of Major
.
Summary
The wording of the table is currently ambiguous, so I've added more words around it and also added an examples table.
I thought carefully about the table, but I'm a) not certain of the actual intended semantics, and b) not certain I got the table right even given the semantics. So please don't assume I know what I'm doing here.
As a check, I asked Claude 3.7 Sonnet to write the same table, but it resolved the ambiguity in the original docs differently from the way I did; it picked
8.2.0
rather than8.2.3
in the left-hand column, because it resolved the ambiguity in the direction of "lowest patch number" rather than "highest patch number". I only went with "highest patch number" because of the stated downside ofDisable
, preventing roll-forward to latest patch versions.Internal previews