Add examples to roll-forward table #46238
Conversation
dotnet-policy-service
bot
added
the
community-contribution
There was a problem hiding this comment.
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.
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.
Oh good point; I'll move it to
docs/docs/core/versions/selection.md
Line 160 in 58615fb
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.
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.
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.0rather than8.2.3in 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