Merge pull request NuGet#1309 from NuGet/master

master -> live

Author: Karan Nandwani

docs/api/overview.md

@@ -53,17 +53,17 @@ Non-breaking protocol changes have been made to the API since it was first relea
 
 The **service index** describes a variety of resources. The current set of supported resources are as follows:
 
-Resource name                                                           | Required | Description
-----------------------------------------------------------------------  | -------- | -----------
+Resource name                                                          | Required | Description
+---------------------------------------------------------------------- | -------- | -----------
 [`PackagePublish`](package-publish-resource.md)                        | yes      | Push and delete (or unlist) packages.
 [`SearchQueryService`](search-query-service-resource.md)               | yes      | Filter and search for packages by keyword.
 [`RegistrationsBaseUrl`](registration-base-url-resource.md)            | yes      | Get package metadata.
 [`PackageBaseAddress`](package-base-address-resource.md)               | yes      | Get package content (.nupkg).
 [`SearchAutocompleteService`](search-autocomplete-service-resource.md) | no       | Discover package IDs and versions by substring.
 [`ReportAbuseUriTemplate`](report-abuse-resource.md)                   | no       | Construct a URL to access a "report abuse" web page.
-[`RepositorySignatures`](repository-signatures-resource.md)             | no      | Get certificates used for repository signing.
-[`Catalog`](catalog-resource.md)                                         | no      | Full record of all package events.
-[`SymbolPackagePublish`](symbol-package-publish-resource.md)            | no      | Push symbol packages.
+[`RepositorySignatures`](repository-signatures-resource.md)            | no       | Get certificates used for repository signing.
+[`Catalog`](catalog-resource.md)                                       | no       | Full record of all package events.
+[`SymbolPackagePublish`](symbol-package-publish-resource.md)           | no       | Push symbol packages.
 
 In general, all non-binary data returned by a API resource are serialized using JSON. The response schema
 returned by each resource in the service index is defined individually for that resource. For more information about
@@ -79,6 +79,26 @@ that the implementation does not understand should be ignored.
 > report abuse URL (tracked by [NuGet/Home#4924](https://github.com/NuGet/Home/issues/4924)). Other clients may opt
 > to simply not show a report abuse URL to the user.
 
+### Undocumented resources on nuget.org
+
+The V3 service index on nuget.org has some resources that are not documented above. There are a few reasons for not
+documenting a resource.
+
+First, we don't document resources used as an implementation detail of nuget.org. The `SearchGalleryQueryService`
+falls into this category. [NuGetGallery](https://github.com/NuGet/NuGetGallery) uses this resource to delegate some V2
+(OData) queries to our search index instead of using the database. This resource was introduced for scalability reasons
+and is not intended for external use.
+
+Second, we don't document resources that never shipped in an RTM version of the official client.
+`PackageDisplayMetadataUriTemplate` and `PackageVersionDisplayMetadataUriTemplate` fall into this category.
+
+Thirdly, we don't document resources that are tightly coupled with the V2 protocol, which itself is intentionally
+undocumented. The `LegacyGallery` resource falls into this category. This resource allows a V3 service index to point to
+a corresponding V2 source URL. This resource supports the `nuget.exe list`.
+
+If a resource is not documented here, we *strongly* recommend that you do not take a dependency on them. We may remove
+or change the behavior of these undocumented resources which could break your implementation in unexpected ways.
+
 ## Timestamps
 
 All timestamps returned by the API are UTC or are otherwise specified using

docs/create-packages/Native-Packages.md

@@ -9,7 +9,7 @@ ms.topic: conceptual
 
 # Creating native packages
 
-A native package contains native C++ code instead of managed code, allowing it to be used within C++ projects. (See [Native C++ Packages](../consume-packages/finding-and-choosing-packages.md#native-c-packages) in the Consume section.)
+A native package contains native binaries instead of managed assemblies, allowing it to be used within C++ (or similar) projects. (See [Native C++ Packages](../consume-packages/finding-and-choosing-packages.md#native-c-packages) in the Consume section.)
 
 To be consumable in a C++ project, a package must target the `native` framework. At present there are not any version numbers associated with this framework as NuGet treats all C++ projects the same.
 

docs/faqs/NuGet-FAQ.md

@@ -232,15 +232,13 @@ If that fails, try the [tips mentioned in this StackOverflow post](http://stacko
 
 ## What is the API endpoint for nuget.org?
 
-To use  nuget.org as a package repository with NuGet clients, you would need to use the following V3 API endpoint: 
+To use nuget.org as a package repository with NuGet clients, you should use the following V3 API endpoint: 
 
 **`https://api.nuget.org/v3/index.json`**
 
-Older clients can still use the v2 protocol to reach nuget.org. However, please note, NuGet clients 3.0 or later will have slower and less-reliable service using the v2 protocol:
+Older clients can still use the V2 protocol to reach nuget.org. However, please note, NuGet clients 3.0 or later will have slower and less-reliable service using the V2 protocol:
 
-`https://www.nuget.org/api/v2/` (DEPRECATED!!!) **Note:** the "www." is important.
-
-Additionally, *NuGet.exe List* only works with the v2 protocol.
+`https://www.nuget.org/api/v2` (DEPRECATED!!!) **Note:** use "www." for the best reliability.
 
 ## nuget.org account management
 

docs/hosting-packages/Overview.md

@@ -20,7 +20,7 @@ For all such purposes, NuGet supports setting up private package sources in the
 
 There are also several other NuGet hosting products that support remote private feeds, including the following:
 
-- [Visual Studio Team Services Package Management](https://www.visualstudio.com/docs/package/nuget/publish), which is also available on Team Foundation Server 2017 and later.
+- [Azure Artifacts](https://www.visualstudio.com/docs/package/nuget/publish), which is also available on Team Foundation Server 2017 and later.
 - [MyGet](http://myget.org)
 - [ProGet](http://inedo.com/proget) from Inedo
 - [NuGet Server](http://nugetserver.net/), a community project from Inedo

docs/quickstart/create-and-publish-a-package-using-the-dotnet-cli.md

@@ -104,4 +104,5 @@ Once you have a `.nupkg` file, you publish it to nuget.org using the `dotnet nug
 - [Support multiple target frameworks](../create-packages/supporting-multiple-target-frameworks.md)
 - [Package versioning](../reference/package-versioning.md)
 - [Creating localized packages](../create-packages/creating-localized-packages.md)
+- [Creating symbol packages](../create-packages/symbol-packages-snupkg.md)
 - [Signing packages](../create-packages/Sign-a-package.md)

docs/tools/cli-ref-pack.md

@@ -38,7 +38,7 @@ where `<nuspecPath>` and `<projectPath>` specify the `.nuspec` or project file,
 | IncludeReferencedProjects | Indicates that the built package should include referenced projects either as dependencies or as part of the package. If a referenced project has a corresponding `.nuspec` file that has the same name as the project, then that referenced project is added as a dependency. Otherwise, the referenced project is added as part of the package. |
 | MinClientVersion | Set the *minClientVersion* attribute for the created package. This value will override the value of the existing *minClientVersion* attribute (if any) in the `.nuspec` file. |
 | MSBuildPath | *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. |
-| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. |
+| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. |
 | NoDefaultExcludes | Prevents default exclusion of NuGet package files and files and folders starting with a dot, such as `.svn` and `.gitignore`. |
 | NoPackageAnalysis | Specifies that pack should not run package analysis after building the package. |
 | OutputDirectory | Specifies the folder in which the created package is stored. If no folder is specified, the current folder is used. |

docs/tools/cli-ref-restore.md

@@ -34,7 +34,7 @@ where `<projectPath>` specifies the location of a solution or a `packages.config
 | ForceEnglishOutput | *(3.5+)* Forces nuget.exe to run using an invariant, English-based culture. |
 | Help | Displays help information for the command. |
 | MSBuildPath | *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. |
-| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. |
+| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. |
 | NoCache | Prevents NuGet from using cached packages. See [Managing the global packages and cache folders](../consume-packages/managing-the-global-packages-and-cache-folders.md). |
 | NonInteractive | Suppresses prompts for user input or confirmations. |
 | OutputDirectory | Specifies the folder in which packages are installed. If no folder is specified, the current folder is used. Required when restoring with a `packages.config` file unless `PackagesDirectory` or `SolutionDirectory` is used.|

docs/tools/cli-ref-update.md

@@ -37,7 +37,7 @@ where `<configPath>` identifies either a `packages.config` or solution file that
 | Help | Displays help information for the command. |
 | Id | Specifies a list of package IDs to update. |
 | MSBuildPath | *(4.0+)* Specifies the path of MSBuild to use with the command, taking precedence over `-MSBuildVersion`. |
-| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. |
+| MSBuildVersion | *(3.2+)* Specifies the version of MSBuild to be used with this command. Supported values are 4, 12, 14, 15.1, 15.3, 15.4, 15.5, 15.6, 15.7, 15.8, 15.9. By default the MSBuild in your path is picked, otherwise it defaults to the highest installed version of MSBuild. |
 | NonInteractive | Suppresses prompts for user input or confirmations. |
 | PreRelease | Allows updating to prerelease versions. This flag is not required when updating prerelease packages that are already installed. |
 | RepositoryPath | Specifies the local folder where packages are installed. |