Merge pull request NuGet#770 from NuGet/kraigb-feedback

Revising cache topic, clarifying global-packages vs. cache

Author: kraigb

.openpublishing.redirection.json

@@ -20,6 +20,11 @@
             "redirect_url": "/nuget/reference/extensibility/nuget-exe-credential-providers",
             "redirect_document_id": false
         },
+        {
+            "source_path": "docs/consume-packages/managing-the-nuget-cache.md",
+            "redirect_url": "/nuget/consume-packages/managing-the-global-packages-and-cache-folders",
+            "redirect_document_id": false
+        },
         {
             "source_path": "docs/create-packages/Dependency-Versions.md",
             "redirect_url": "/nuget/reference/package-versioning",

README.md

@@ -31,8 +31,7 @@ No contribution is too big or too small--
 If you're creating a new topic, keep the following in mind as well:
 
 1. Always place the new topic in an appropriate subfolder, and follow the conventions for filenames as you see them used here.
-1. You must include a metadata block as you see on other topics. The fields you should change are the following: title, ms.date, ms.assetid, description, and keywords.
-    1. For ms.assetid, always create a new GUID for a new topic.
+1. You must include a metadata block as you see on other topics. The fields you should change are the following: title, ms.date, description, and keywords.
     1. Leave the ms.author and manager fields set as they are, because these are used to manage ownership internally.
     1. Ideally for SEO, the title field and the top-level # heading of the topic are different; see various topics for examples.
 1. In addition to adding your page, edit docs/TOC.md to add a link to that page.

docs/TOC.md

@@ -14,7 +14,7 @@
 ### [Troubleshooting](consume-packages/package-restore-troubleshooting.md)
 ## [Reinstalling and updating packages](consume-packages/reinstalling-and-updating-packages.md)
 ## [Packages and source control](consume-packages/packages-and-source-control.md)
-## [Managing the NuGet cache](consume-packages/managing-the-nuget-cache.md)
+## [Managing the global packages and cache folders](consume-packages/managing-the-global-packages-and-cache-folders.md)
 ## [Configuring NuGet behavior](consume-packages/configuring-nuget-behavior.md)
 ## [Dependency resolution](consume-packages/dependency-resolution.md)
 # Create packages
@@ -31,8 +31,8 @@
 ## Guides
 ### [Create UWP packages](guides/create-uwp-packages.md)
 ### [Creating UWP controls as NuGet packages](guides/create-uwp-controls.md)
-### [Create NET Standard packages (Visual Studio 2015)](guides/create-net-standard-packages-vs2015.md)
-### [Create packages for Xamarin](guides/create-packages-for-xamarin.md)
+### [Create NET Standard/NET Framework packages with Visual Studio 2015](guides/create-net-standard-packages-vs2015.md)
+### [Create packages for Xamarin with Visual Studio 2015](guides/create-packages-for-xamarin.md)
 # Host packages
 ## [Overview](hosting-packages/overview.md)
 ## [Local feeds](hosting-packages/local-feeds.md)
@@ -88,7 +88,7 @@
 ### [NuGet credential providers for Visual Studio](reference/extensibility/nuget-credential-providers-for-visual-studio.md)
 ### [nuget.exe credential providers](reference/extensibility/nuget-exe-credential-providers.md)
 ## Archived content
-### [project.json reference format](archive/project-json.md)
+### [project.json management format](archive/project-json.md)
 ### [project.json and UWP](archive/project-json-and-uwp.md)
 ### [project.json impact](archive/project-json-impact.md)
 # API

docs/archive/project-json-archive.md

@@ -19,19 +19,19 @@ ms.workload:
 
 # project.json archive
 
-The `project.json` reference format was introduced with NuGet 3.x and used for certain project types. It was deprecated with the introduction of the PackageReference format, in which dependencies are listed directly in a project file.
+The `project.json` management format was introduced with NuGet 3.x and used for certain project types. It was deprecated with the introduction of the PackageReference format, in which dependencies are listed directly in a project file.
 
 Also see:
 
 - [project.json schema](project-json.md)
 - [project.json impact on package authors](project-json-impact.md)
 - [project.json and UWP](project-json-and-uwp.md)
 
-## project.json reference format
+## project.json management format
 
 *Originally in [Package restore](../what-is-nuget.md).*
 
-In the list of reference formats:
+In the list of management formats:
 
 - [`project.json`](project-json.md): *(deprecated)* A JSON file that maintains a list of the project's dependencies with an overall package graph in an associated file, `project.lock.json`. This format is deprecated in favor of PackageReference.
 
@@ -137,7 +137,7 @@ When using the `project.json` format, NuGet also supports using a wildcard notat
 
 *Originally in [NuGet.Config reference](../reference/nuget-config-file.md).*
 
-`globalPackagesFolder` applies only to `project.json`.
+`globalPackagesFolder` applies only to `project.json`. (Added note: also applies to PackageReference.)
 
 ### nuspec file reference
 
@@ -149,7 +149,7 @@ The `<contentFiles>` element is used instead of `<files>` with `project.json`.
 
 *Originally in [Package Manager UI reference](../tools/package-manager-ui.md).*
 
-Projects using `project.json` reference format show only the **Show preview window** option.
+Projects using `project.json` management format show only the **Show preview window** option.
 
 ### Visual Studio Templates
 

docs/archive/project-json.md

@@ -21,7 +21,7 @@ ms.workload:
 
 *NuGet 3.x+*
 
-The `project.json` file maintains a list of packages used in a project, known as a package reference format. It supersedes `packages.config` but is in turn superseded by [PackageReference](../consume-packages/package-references-in-project-files.md) with NuGet 4.0+.
+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+.
 
 The [`project.lock.json`](#projectlockjson) file (described below) is also used in projects employing `project.json`.
 
@@ -121,7 +121,7 @@ Lists the frameworks that the project runs on, such as `net45`, `netcoreapp`, `n
     }
  ```
 
-Only a single entry is allowed in the `frameworks` section. (An exception is `project.json` files for ASP.NET projects that are build with deprecated DNX toolchain, which allows for multiple targets.)
+Only a single entry is allowed in the `frameworks` section. (An exception is `project.json` files for ASP.NET projects that are build with deprecated DNX tool chain, which allows for multiple targets.)
 
 ## Runtimes
 

docs/consume-packages/Configuring-NuGet-Behavior.md

@@ -26,7 +26,7 @@ NuGet's behavior is driven by the accumulated settings in one or more `NuGet.Con
 | Scope | NuGet.Config file location | Description |
 | --- | --- | --- |
 | Project | Current folder (aka Project folder) or any folder up to the drive root.| In a project folder, settings apply only to that project. In parent folders that contain multiple projects subfolders, settings apply to all projects in those subfolders. |
-| User | Windows: `%APPDATA%\NuGet\NuGet.Config`<br/>Mac/Linux: `~/.nuget/NuGet/NuGet.Config` | Settings apply to all operations, but are overridden by any project-level settings. |
+| User | Windows: `%appdata%\NuGet\NuGet.Config`<br/>Mac/Linux: `~/.nuget/NuGet/NuGet.Config` | Settings apply to all operations, but are overridden by any project-level settings. |
 | Computer | Windows: `%ProgramFiles(x86)%\NuGet\Config`<br/>Mac/Linux: `$XDG_DATA_HOME` (typically `~/.local/share`) | Settings apply to all operations on the computer, but are overriden by any user- or project-level settings. |
 
 Notes for earlier versions of NuGet:
@@ -136,7 +136,7 @@ Let's say you have the following folder structure on two separate drives:
 
 You then have four `NuGet.Config` files in the following locations with the given content. (The computer-level file is not included in this example, but would behave similarly to the user-level file.)
 
-File A. User-level file, (`%APPDATA%\NuGet\NuGet.Config` on Windows, `~/.nuget/NuGet/NuGet.Config` on Mac/Linux):
+File A. User-level file, (`%appdata%\NuGet\NuGet.Config` on Windows, `~/.nuget/NuGet/NuGet.Config` on Mac/Linux):
 
 ```xml
 <?xml version="1.0" encoding="utf-8"?>
@@ -219,7 +219,7 @@ The following table describes where the `NuGetDefaults.Config` file should be st
 
 ### NuGetDefaults.Config settings
 
-- `packageSources`: this collection has the same meaning as `packageSources` in regular config files and specifies the default sources. NuGet uses the sources in order when installing or updating packages in projects using the `packages.config` reference format. For projects using the PackageReference format, NuGet uses local sources first, then sources on network shares, then HTTP sources, regardless of the order in the configuration files. NuGet always ignores the order of sources with restore operations.
+- `packageSources`: this collection has the same meaning as `packageSources` in regular config files and specifies the default sources. NuGet uses the sources in order when installing or updating packages in projects using the `packages.config` management format. For projects using the PackageReference format, NuGet uses local sources first, then sources on network shares, then HTTP sources, regardless of the order in the configuration files. NuGet always ignores the order of sources with restore operations.
 
 - `disabledPackageSources`: this collection also has the same meaning as in `NuGet.Config` files, where each affected source is listed by its name and a true/false value indicating whether it's disabled. This allows the source name and URL to remain in `packageSources` without having it turned on by default. Individual developers can then re-enable the source by setting the source's value to false in other `NuGet.Config` files without having to find the correct URL again. This is also useful to supply developers with a full list of internal source URLs for an organization while enabling only an individual team's source by default.
 

docs/consume-packages/Dependency-Resolution.md

@@ -23,7 +23,7 @@ Any time a package is installed or reinstalled, which includes being installed a
 
 Those immediate dependencies might then also have dependencies on their own, which can continue to an arbitrary depth. This produces what's called a *dependency graph* that describes the relationships between packages at all levels.
 
-When multiple packages have the same dependency, then the same package ID can appear in the graph multiple times, potentially with different version constraints. However, only one version of a given package can be used in a project, so NuGet must choose which version is used. The exact process depends on the package reference format being used.
+When multiple packages have the same dependency, then the same package ID can appear in the graph multiple times, potentially with different version constraints. However, only one version of a given package can be used in a project, so NuGet must choose which version is used. The exact process depends on the package management format being used.
 
 ## Dependency resolution with PackageReference
 
@@ -108,7 +108,7 @@ With `packages.config`, NuGet attempts to resolve dependency conflicts during th
 
 By default, NuGet 2.8 looks for the lowest patch version (see [NuGet 2.8 release notes](../release-notes/nuget-2.8.md#patch-resolution-for-dependencies)). You can control this setting through the `DependencyVersion` attribute in `Nuget.Config` and the `-DependencyVersion` switch on the command line.  
 
-The `packages.config` process for resolving dependencies gets complicated for larger dependency graphs. Each new package installation requires a traversal of the whole graph and raises the chance for version conflicts. When a conflict occurs, installation is stopped, leaving the project in an indeterminate state, especially with potential modifications to the project file itself. This is not an issue when using other package reference formats.
+The `packages.config` process for resolving dependencies gets complicated for larger dependency graphs. Each new package installation requires a traversal of the whole graph and raises the chance for version conflicts. When a conflict occurs, installation is stopped, leaving the project in an indeterminate state, especially with potential modifications to the project file itself. This is not an issue when using other package management formats.
 
 ## Managing dependency assets
 
@@ -120,7 +120,7 @@ When the top-level project is itself a package, you also have control over this
 
 There are scenarios in which assemblies with the same name might be referenced more than once in a project, producing design-time and build-time errors. Consider a project that contains a custom version of `C.dll`, and references Package C that also contains `C.dll`. At the same time, the project also depends on Package B which also depends on Package C and `C.dll`. As a result, NuGet can't determine which `C.dll` to use, but you can't just remove the project's dependency on Package C because Package B also depends on it.
 
-To resolve this, you must directly reference the `C.dll` you want (or use another package that references the right one), and then add a dependency on Package C that excludes all its assets. This is done as follows depending on the package reference format in use:
+To resolve this, you must directly reference the `C.dll` you want (or use another package that references the right one), and then add a dependency on Package C that excludes all its assets. This is done as follows depending on the package management format in use:
 
 - [PackageReference](../consume-packages/package-references-in-project-files.md): add `Exclude="All"` in the dependency: