Merge pull request #3392 from NuGet/main

Public main to live

Author: nkolev92

docs/archive/media/project-json-migrator.png

@@ -10,7 +10,8 @@ ms.topic: conceptual
 # project.json and UWP
 
 > [!Important]
-> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats.
+> This content is deprecated. Projects should use the PackageReference formats.
+> Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference).
 
 This document describes the package structure that employs features in NuGet 3+ (Visual Studio 2015 and later). The `minClientVersion` property of your `.nuspec` can be used to state that you require the features described here by setting it to 3.1.
 

docs/archive/project-json-and-uwp.md

@@ -10,7 +10,8 @@ ms.topic: conceptual
 # Impact of project.json when creating packages
 
 > [!Important]
-> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats.
+> This content is deprecated. Projects should use the PackageReference formats.
+> Learn how to [migrate your project.json project to PackageReference](./project-json.md#migrate-projectjson-to-packagereference).
 
 The `project.json` system used in NuGet 3+ affects package authors in several ways as described in the following sections.
 

docs/archive/project-json-impact.md

@@ -10,9 +10,10 @@ ms.topic: reference
 # project.json reference
 
 > [!Important]
-> This content is deprecated. Projects should use either the `packages.config` or PackageReference formats.
+> This content is deprecated. Projects should use the PackageReference formats.
+> Learn how to [migrate your project.json project to PackageReference](#migrate-projectjson-to-packagereference).
 
-*NuGet 3.x+*
+*NuGet 3.x*
 
 The `project.json` file maintains a list of packages used in a project, known as a package management format. It supersedes `packages.config` but is in turn superseded by [PackageReference](../consume-packages/package-references-in-project-files.md) with NuGet 4.0+.
 
@@ -37,6 +38,18 @@ The [`project.lock.json`](#projectlockjson) file (described below) is also used
 }
 ```
 
+## Migrate project.json to PackageReference
+
+The migration between project.json and PackageReference is straightforward. The easiest way to do it to use the built-in migrator in the latest Visual Studio 2022, Update 14.
+
+1. Load the project.json project in Visual Studio.
+1. Go to the solution explorer of the project.json project and find the dependencies node.
+1. Click `Migrate project.json to PackageReference...`!
+
+![Migrating from project.json to PackageReference](media/project-json-migrator.png)
+
+Alternatively, you may use the [dotnet migrate](/dotnet/core/tools/dotnet-migrate), or do the migration manually by taking all of the content from the project.json file and replacing it with the equivalent [PackageReference syntax](../consume-packages/Package-References-in-Project-Files.md).
+
 ## Dependencies
 
 Lists the NuGet package dependencies of your project in the following form:

docs/archive/project-json.md

@@ -63,6 +63,7 @@ When using a floating version, NuGet resolves the highest version of a package t
 | 1.1.* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.2.0-alpha | 1.1.1 | The highest stable version that respects the specified pattern.|
 | \*-\* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.3.0-beta  | 1.3.0-beta | The highest version including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 |
 | 1.1.\*-\* | 1.1.0 <br> 1.1.1 <br> 1.1.2-alpha <br> 1.1.2-beta <br> 1.3.0-beta  | 1.1.2-beta | The highest version respecting the pattern and including the not stable versions. | Available in Visual Studio version 16.6, NuGet version 5.6, .NET Core SDK version 3.1.300 |
+| 1.2.0-rc.* | 1.1.0 <br> 1.2.0-rc.1 <br> 1.2.0-rc.2 <br> 1.2.0 | 1.2.0 | Despite this being a version range with a prerelease part, stables are allowed if they match the stable part. Given that 1.2.0 > 1.2.0-rc.2, it is chosen. |  |
 
 > [!Note]
 > Floating version resolution does not take into account whether or not a package is listed.

docs/concepts/Dependency-Resolution.md

@@ -38,6 +38,11 @@ Central package management applies to all `<PackageReference>`-based MSBuild pro
 To get started with central package management, you must create a `Directory.Packages.props` file at the root of your repository and set the MSBuild property
 `ManagePackageVersionsCentrally` to `true`.
 
+You can create it manually or you can use the dotnet CLI:
+``` shell
+dotnet new packagesprops
+```
+
 Inside, you then define each of the respective package versions required of your projects using `<PackageVersion />` elements that define the package ID and
 version.
 
@@ -117,6 +122,7 @@ For an idea of how central package management may look like, refer to our [sampl
 
 You can automatically override a transitive package version even without an explicit top-level `<PackageReference />` by opting into a feature known as
 transitive pinning. This promotes a transitive dependency to a top-level dependency implicitly on your behalf when necessary.
+Note that downgrades are allowed when transitive pinning a package. If you attempt to pin a package to a lower version than the one requested by your dependencies, restore will raise a [NU1109](../reference/errors-and-warnings/NU1109.md) error.
 
 You can enable this feature by setting the MSBuild property `CentralPackageTransitivePinningEnabled` to `true` in a project or in a `Directory.Packages.props`
 or `Directory.Build.props` import file:
@@ -127,6 +133,45 @@ or `Directory.Build.props` import file:
 </PropertyGroup>
 ```
 
+### Transitive pinning and pack
+
+When a package is transitively pinned, your project uses a higher than the one requested by your dependencies.
+If you create a package from your project, in order to ensure that your package will work, NuGet will promote the transitively pinned dependencies to explicit dependencies in the nuspec.
+
+In the following example, `PackageA 1.0.0` has a dependency on `PackageB 1.0.0`.
+
+```xml
+<Project>
+  <ItemGroup>
+    <PackageVersion Include="PackageA" Version="1.0.0" />
+    <PackageVersion Include="PackageB" Version="2.0.0" />
+  </ItemGroup>
+</Project>
+```
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <CentralPackageTransitivePinningEnabled>true</CentralPackageTransitivePinningEnabled>
+    <TargetFramework>net6.0</TargetFramework>
+  </PropertyGroup>
+  <ItemGroup>
+    <PackageReference Include="PackageA" />
+  </ItemGroup>
+</Project>
+```
+
+When you use the pack command to create a package, both packages will appear in the dependency group.
+
+```xml
+      <group targetFramework="net6.0">
+        <dependency id="PackageA" version="6.12.1" exclude="Build,Analyzers" />
+        <dependency id="PackageB" version="6.12.1" exclude="Build,Analyzers" />
+      </group>
+```
+
+Because of this, the use of transitive pinning should be carefully evaluated when authoring a library as it may lead to dependencies you did not expect.
+
 ## Overriding package versions
 
 You can override an individual package version by using the `VersionOverride` property on a `<PackageReference />` item. This overrides any `<PackageVersion />`
@@ -176,6 +221,7 @@ If you'd like to disable central package management for any a particular project
 ```
 
 ## Global Package References
+
 > [!Note]
 > This feature is only available in Visual Studio 2022 17.4 or higher, .NET SDK 7.0.100.preview7 or higher, and NuGet 6.4 or higher.
 

docs/consume-packages/Central-Package-Management.md

@@ -39,5 +39,6 @@ There are also several other NuGet hosting products such as [Azure Artifacts](ht
 - [ProGet](https://inedo.com/proget) from Inedo
 - [Sleet](https://github.com/emgarten/sleet), an open-source NuGet V3 static feed generator
 - [TeamCity](https://www.jetbrains.com/teamcity/) from JetBrains.
+- [RepoFlow](https://www.repoflow.io), a simple and easy-to-use package management platform.
 
 Regardless of how packages are hosted, you access them by adding them to the list of available sources in `NuGet.Config`. This can be done in Visual Studio as described in [Package Sources](../consume-packages/install-use-packages-visual-studio.md#package-sources), or from the command line using [`nuget sources`](../reference/cli-reference/cli-ref-sources.md). The path to a source can be a local folder pathname, a network name, or a URL.

docs/hosting-packages/Overview.md

@@ -107,5 +107,7 @@ nuget sources Enable -Name "nuget.org"
 
 nuget sources add -name foo.bar -source C:\NuGet\local -username foo -password bar -StorePasswordInClearText -configfile %AppData%\NuGet\my.config
 
+nuget sources add -name MyAzureDevOpsSource -source "https://pkgs.dev.azure.com/yourorgname/yourprojectname/_packaging/yourfeedname/nuget/v3/index.json" -username ignored -password <Personal Access Token>
+
 nuget sources Update -Name "nuget.org" -ProtocolVersion 3
 ```