From 7299fd9d290cdafd25c6a28bc232564aa7550e1c Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Fri, 6 Jan 2023 15:28:03 -0800 Subject: [PATCH 1/2] design spec for version property in project reference --- ...ow-version-property-in-projectreference.md | 107 ++++++++++++++++++ 1 file changed, 107 insertions(+) create mode 100644 proposed/2023/allow-version-property-in-projectreference.md diff --git a/proposed/2023/allow-version-property-in-projectreference.md b/proposed/2023/allow-version-property-in-projectreference.md new file mode 100644 index 000000000..3a5fd1749 --- /dev/null +++ b/proposed/2023/allow-version-property-in-projectreference.md @@ -0,0 +1,107 @@ +# Allow users to define version ranges for ProjectReferences + +- [Martin Ruiz](https://github.com/martinrrm) +- Start Date (2023-01-01) +- [5556](https://github.com/NuGet/Home/issues/5556) + +# Summary + +Add a `Version` to `ProjectReference` tag in CSPROJ, to allow customers to specify the referenced project version in the `.nupkg` and `nuspec` files when doing a pack command. + +# Motivation + +When using `ProjectReference` there is no option to define a Version to the reference like in `PackageReference` and the version will always be defined as `>= ProjectVersion`, this results in customers manually modifying the nuspec file if they want to declare a different version than the project version. + +# Explanation + +Currently when adding a `ProjectReference` to a project, there is no property to specify which version(s) of it to be used when doing a pack. +When doing a pack to a package with a `ProjectRefernce` it will always be added as a range, where the minumum version will be the ProjectReference version and with an open maximum version. + +``` + + + +``` + +Add a `Version` property to `ProjectReference` and store that value in the assets file when doing a restore so we can retrieve that information when doing a `pack command. + +If there is no `Version` information then the behavior should be the current one. + +## Example + +### .CSPROJ file +``` + + + + +``` + +### assets file +``` +"frameworks": { + "net6.0": { + "targetAlias": "net6.0", + "projectReferences": { + "C:\\Users\\mruizmares\\source\\repos\\ConsoleApp1\\MyReferencedPackage\\MyReferencedPackage.csproj": { + "projectPath": "C:\\Users\\mruizmares\\source\\repos\\ConsoleApp1\\MyReferencedPackage\\MyReferencedPackage.csproj", + "version": "[1.0.0, 2.0.0)" + } + } + } +}, +``` + +### nuspec file +``` + + + + ConsoleApp1 + 1.2.4 + ConsoleApp1 + Package Description + + + + + + + + + + + + +``` + +### nupkg +``` +Metadata: + id: ConsoleApp1 + version: 1.2.4 + authors: ConsoleApp1 + description: Package Description +Dependencies: + net6.0: + MyReferencedPackage: '>= 1.0.0 && < 2.0.0' + Newtonsoft.Json: '>= 9.0.0 && < 13.0.2' + +Contents: + - File: _rels/.rels + - File: [Content_Types].xml + - File: ConsoleApp1.nuspec + - File: lib/net6.0/ConsoleApp1.dll + - File: lib/net6.0/ConsoleApp1.runtimeconfig.json + - File: package/services/metadata/core-properties/a638a18cb3b1449185ce67e16a13ebaf.psmdcp +``` + +# Drawbacks + +I don't think there are drawbacks to this implementation when doing a `pack` command. For restore I'm not sure if adding a new propert to the assets file can affect the performance. + +# Rationale and alternatives + +# Unresolved Questions + +# Future Possibilities \ No newline at end of file From 4a4c9248b9841d6085b5fdad74ad726e9ff41781 Mon Sep 17 00:00:00 2001 From: Martin Ruiz Date: Mon, 17 Apr 2023 11:29:08 -0700 Subject: [PATCH 2/2] pr comments feedback, multiple options --- ...ow-version-property-in-projectreference.md | 100 +++++++++++++++++- 1 file changed, 97 insertions(+), 3 deletions(-) diff --git a/proposed/2023/allow-version-property-in-projectreference.md b/proposed/2023/allow-version-property-in-projectreference.md index 3a5fd1749..c4d029c2b 100644 --- a/proposed/2023/allow-version-property-in-projectreference.md +++ b/proposed/2023/allow-version-property-in-projectreference.md @@ -15,7 +15,7 @@ When using `ProjectReference` there is no option to define a Version to the refe # Explanation Currently when adding a `ProjectReference` to a project, there is no property to specify which version(s) of it to be used when doing a pack. -When doing a pack to a package with a `ProjectRefernce` it will always be added as a range, where the minumum version will be the ProjectReference version and with an open maximum version. +When doing a pack to a package with a `ProjectReference` it will always be added as a range, where the minimum version will be the ProjectReference version and with an open maximum version. ``` @@ -23,11 +23,19 @@ When doing a pack to a package with a `ProjectRefernce` it will always be added ``` -Add a `Version` property to `ProjectReference` and store that value in the assets file when doing a restore so we can retrieve that information when doing a `pack command. +Add a `Version` property to `ProjectReference` and store that value in the assets file when doing a restore so we can retrieve that information when doing a `pack` command. + + +## Considerations If there is no `Version` information then the behavior should be the current one. -## Example +If the `Version` is not a range, it will be treated as one, like in `PackageReference`. `Version="2.0.0"` means `Version="[2.0.0, )"` + +Minimum version should not be open to users, and NuGet should always automatically fill in the min version from the project's version, this is for the protection of package consumers. + +--- +## Option 1 - Version with VersionRange ### .CSPROJ file ``` @@ -37,6 +45,23 @@ If there is no `Version` information then the behavior should be the current one ``` +### Explanation +`Version` will be a version range, but the lower version will be replaced with the actual `Version` as an inclusive min version. + +We will log a warning saying that the min version should be equal to the `ProjectVersion` and it was replaced. + +## Option 2 - Version without defined min version +### .CSPROJ file +``` + + + + +``` + +### Explanation +`Version` will be a version range, but the lower version will be defined by a 'X' and replaced with the actual `ProjectVersion` as an inclusive min version. + ### assets file ``` "frameworks": { @@ -102,6 +127,75 @@ I don't think there are drawbacks to this implementation when doing a `pack` com # Rationale and alternatives +## Option 3 - Separate variables for max project version. +### .CSPROJ file +``` + + + + +``` + +### assets file +``` +"frameworks": { + "net6.0": { + "targetAlias": "net6.0", + "projectReferences": { + "C:\\Users\\mruizmares\\source\\repos\\ConsoleApp1\\MyReferencedPackage\\MyReferencedPackage.csproj": { + "projectPath": "C:\\Users\\mruizmares\\source\\repos\\ConsoleApp1\\MyReferencedPackage\\MyReferencedPackage.csproj", + "MaxProjectVersion": "3.0.2" + "IsMaxProjectVersionInclusive": "true" + } + } + } +}, +``` + +### nuspec file +``` + + + + ConsoleApp1 + 1.2.4 + ConsoleApp1 + Package Description + + + + + + + + + + + + +``` + +### nupkg +``` +Metadata: + id: ConsoleApp1 + version: 1.2.4 + authors: ConsoleApp1 + description: Package Description +Dependencies: + net6.0: + MyReferencedPackage: '>= 1.0.0 && <= 3.0.2' + Newtonsoft.Json: '>= 9.0.0 && < 13.0.2' + +Contents: + - File: _rels/.rels + - File: [Content_Types].xml + - File: ConsoleApp1.nuspec + - File: lib/net6.0/ConsoleApp1.dll + - File: lib/net6.0/ConsoleApp1.runtimeconfig.json + - File: package/services/metadata/core-properties/a638a18cb3b1449185ce67e16a13ebaf.psmdcp +``` + # Unresolved Questions # Future Possibilities \ No newline at end of file