more edits in flight

mikeblome · mikeblome · commit d7d2855c8b7f · 2019-10-25T16:07:11.000-07:00
diff --git a/docs/porting/binary-compat-2015-2017.md b/docs/porting/binary-compat-2015-2017.md
@@ -1,14 +1,14 @@
 ---
-title: "C++ Binary Compatibility between Visual Studio 2015 and Visual Studio 2019"
+title: "C++ binary compatibility between Visual Studio 2015 and Visual Studio 2019"
 ms.date: "10/17/2019"
 helpviewer_keywords: ["binary compatibility, Visual C++"]
 ms.assetid: 591580f6-3181-4bbe-8ac3-f4fbaca949e6
 ---
-# C++ Binary Compatibility between Visual Studio 2015 and Visual Studio 2019
+# C++ binary compatibility between Visual Studio 2015 and Visual Studio 2019
 
 In Visual Studio 2013 and earlier, binary compatibility between object files (OBJs), static libraries (LIBs), dynamic libraries (DLLs), and executables (EXEs) built by using different versions of the compiler toolset and runtime libraries was not guaranteed. 
 
-In Visual Studio 2015 and later, the C++ toolset major number is 14 (v140 for Visual Studio 2015, v141 for Visual Studio 2017, and v142 for Visual Studio 2019). This reflects the fact that both the runtime libraries and the applications compiled with either version of the compiler are binary compatible. This means that if you have third-party library that was built with Visual Studio 2015, you don't have to recompile it in order to consume it from an application that is built with Visual Studio 2017 or Visual Studio 2019.
+In Visual Studio 2015 and later, the C++ toolset major number is 14 (v140 for Visual Studio 2015, v141 for Visual Studio 2017, and v142 for Visual Studio 2019). This reflects the fact that both the runtime libraries and the applications compiled with any of these versions of the compiler are binary compatible. This means that if you have third-party library that was built with Visual Studio 2015, you don't have to recompile it in order to consume it from an application that is built with Visual Studio 2017 or Visual Studio 2019.
 
 The only exception to this rule is that static libraries or object files that are compiled with the `/GL` compiler switch are not binary compatible. 
 
diff --git a/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md b/docs/porting/upgrading-projects-from-earlier-versions-of-visual-cpp.md
@@ -29,15 +29,24 @@ When you upgrade a project, you get an upgrade report, which is also saved in yo
 
 6. Code that no longer compiles due to changes in diagnostics, such as a warning becoming an error
 
-7. Linker errors due to libraries that were changed, especially when /NODEFAULTLIB is used
+7. Linker errors due to libraries that were changed, especially when /NODEFAULTLIB is used.
 
 8. Runtime errors or unexpected results due to behavior changes
 
 9. Errors that were introduced in the tools. If you encounter an issue, report it to the Visual C++ team through your normal support channels or by using the [Visual Studio C++ Developer Community](https://developercommunity.visualstudio.com/spaces/62/index.html) page.
 
-Many upgraded projects and solutions can be built successfully without modification. However, the older the project, the more likely that it will require changes to project settings as well as source code. The C++ code editor displays red squiggles under the errors, and green squiggles to indicate warnings flagged by the default code analysis tools.
+Some upgraded projects and solutions can be built successfully without modification. However, for older projects, it likely that it will require changes to project settings as well as source code. The C++ code editor displays red squiggles under the errors, and green squiggles to indicate warnings flagged by the default code analysis tools. There is no single correct way to go about fixing these, but some kind of phased approach is recommended. See [Overview of potential upgrade issues](../porting/overview-of-potential-upgrade-issues-visual-cpp.md) for more information on many kinds of common errors.
 
-We recommend that you use the following guidelines to address the settings issues first, and then if the project still doesn't build, you can address the code issues. For more information, see [Overview of potential upgrade issues](../porting/overview-of-potential-upgrade-issues-visual-cpp.md).
+ 1. Set the Platform Toolset, C++ Language Standard, and Windows SDK version (if applicable) to the desired versions.
+ 1. If you have a lot of errors, turn off the [permissive-]() option and/or [code analysis]() temporarily to reduce the error count.
+ 1. Ensure that all dependencies are present and that the include paths or library locations are correct.
+ 1. Identify and fix errors due to references to APIs that no longer exist.
+ 1. Fix any remaining errors that prevent compilation.
+ 1. Turn [permissive-]() back on and fix any new errors that appear due to non-conformant code that previously compiled in MSVC.
+ 1. Turn on [code analysis]() to identify potential problems or outdated coding patterns that are no longer considered acceptable. If code analysis flags many errors, you can turn off some of the warnings to focus on the most important ones first. The IDE can help with Quick Fixes for some kinds of issues. See [Upgrade legacy C++ code with Visual Studio](ide-tools-for-upgrading-code.md) for more information.
+ 1. Consider other opportunities for modernizing the code, for example by replacing custom data structures and algorithms with those from the C++ standard library or the Boost open-source library. By using standard features, you make it easier for others to maintain the code and also have a strong confidence that the code has been well-tested and reviewed by many experts on the standards committee and the broader C++ community.
+
+For hard-to-fix errors, post a question on [C++ Developer Community]().
 
 ## In this section
 
diff --git a/docs/porting/use-native-multi-targeting.md b/docs/porting/use-native-multi-targeting.md
@@ -1,6 +1,6 @@
 ---
 title: "Use native multi-targeting in Visual Studio to build old projects"
-ms.date: "11/04/2016"
+ms.date: "10/25/2019"
 helpviewer_keywords: ["C++ native multi-targeting", "upgrading Visual C++ applications, retargeting"]
 ms.assetid: b115aabe-a9dc-4525-90d3-367d97ea20c9
 ---
@@ -36,12 +36,15 @@ If you choose not to upgrade, Visual Studio makes no changes to your solution or
 
 ## Instructions for Visual Studio 2008
 
-Visual Studio 2008 had its own dedicated build system for C++ called **VCBuild**. Starting in Visual Studio 2010, Visual Studio C++ projects were changed to use **MSBuild**. This means that you must go through an update step to build your Visual Studio 2008 projects in the latest version of Visual Studio. Your updated project still generates binaries that are fully compatible with binaries created using the Visual Studio 2008 IDE.
+Visual Studio 2008 had its own dedicated build system for C++ called **VCBuild**. Starting in Visual Studio 2010, Visual Studio C++ projects were changed to use **MSBuild**. This means that whether upgrading permanently or multi-targeting you must go through an update step to build your Visual Studio 2008 projects in the latest version of Visual Studio. Your updated project still generates binaries that are fully compatible with binaries created using the Visual Studio 2008 IDE.
 
 First, in addition to the current version of Visual Studio, you must install Visual Studio 2010 on the same computer as Visual Studio 2008. Only Visual Studio 2010 installs the **MSBuild** scripts that are required to target Visual Studio 2008 projects.
 
 Next, you must update your Visual Studio 2008 solution and projects to the current version of Visual Studio. We recommend you create a backup of your projects and solution files before the upgrade. To start the upgrade process, open the solution in the current version of Visual Studio. When you get the upgrade prompt, review the information presented, and then choose **OK** to start the upgrade. If you have more than one project in the solution, you must update The wizard creates new .vcxproj project files side-by-side with the existing .vcproj files. As long as you also have a copy of the original .sln file, the upgrade has no other impact on your existing Visual Studio 2008 projects.
 
+> [!NOTE]
+> The following steps apply to multi-targeting scenarios only. If you intend to permanently upgrade the project to a later toolset, then your next step is to save the project, open it in Visual Studio 2019, and address the build issues that appear there.
+
 When the upgrade completes, if the log report has errors or warnings for any of your projects, review them carefully. The conversion from **VCBuild** to **MSBuild** can cause issues. Make sure you understand and implement any action items listed in the report. For more information on the upgrade log report and issues that may occur when converting **VCBuild** to **MSBuild**, see this [C++ Native Multi-Targeting](https://blogs.msdn.microsoft.com/vcblog/2009/12/08/c-native-multi-targeting/) blog post.
 
 When the project upgrade is completed, and you have corrected any issues in the log file, your solution actually targets the latest toolset. As the final step, change the properties for each project in the solution to use the Visual Studio 2008 toolset. With the solution loaded in the current version of Visual Studio, for each project in the solution, open the Project **Property Pages** dialog box: Right-click on the project in **Solution Explorer** and then select **Properties**. In the **Property Pages** dialog box, change the **Configuration** drop-down value to **All Configurations**. In **Configuration Properties**, select **General**, and then change **Platform Toolset** to **Visual Studio 2008 (v90)**.
diff --git a/docs/porting/visual-cpp-porting-and-upgrading-guide.md b/docs/porting/visual-cpp-porting-and-upgrading-guide.md
@@ -8,17 +8,21 @@ ms.topic: "overview"
 
 This topic provides a guide for upgrading Microsoft C++ code to the latest version of Visual Studio. This includes getting the code to compile and run correctly on a newer release of the tools, as well as taking advantage of new C++ language features and Visual Studio IDE features. The following scenarios are covered:
 
-- Upgrading from a project created in Visual Studio 2008 or earlier.
-- Upgrading from a project created in Visual Studio 2010 through 2013
-- Upgrading from a project created in Visual Studio 2015 or later
+- Upgrading from a project created in Visual Studio 2008 or earlier. First use Visual Studio 2010 to convert the project to MSBuild format, then open the project in Visual Studio 2019.
+- Upgrading from a project created in Visual Studio 2010 through 2015. Just open the project in Visual Studio 2019. The toolsets in Visual Studio 2015, Visual Studio 2017 and Visual Studio 2019 are binary-compatible, which eliminates the need to upgrade library dependencies.
+- Upgrading to the [Universal CRT](upgrade-your-code-to-the-universal-crt)
 - Upgrading third-party library dependencies
 - Upgrading from earlier versions of the Windows SDK
 - Upgrading to newer C++ language standards
 - Porting from Win32 to the Universal Windows Platform (UWP)
 
-The native Visual Studio build system (MSBuild) was originally designed for Windows applications. Although MSBuild templates are provided for Linux, Android and iOS projects, we recommend using CMake, especially if the project uses open-source libraries or is meant to run on multiple platforms. If upgrading your code to a new toolset is not an option, you can still use recent version of Visual Studio to build and edit projects that target older compiler toolsets and libraries. For more information, see [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md).
+The native Visual Studio build system (MSBuild) was originally designed for Windows applications. MSBuild templates are also provided for remote building of Linux, Android and iOS projects. We recommend moving to CMake in Visual Studio when upgrading projects that use open-source libraries or are meant to run on multiple platforms.
 
-## Reasons to Upgrade C++ Code
+## Multitargeting vs. upgrading
+
+If upgrading your code base to a new toolset is not an option, you can still use a recent version of Visual Studio to build and edit projects that target older compiler toolsets and libraries. For more information, see [Use native multi-targeting in Visual Studio to build old projects](use-native-multi-targeting.md).
+
+## Reasons to upgrade C++ code
 
 If a legacy application is running satisfactorily, in a secure environment, and is not under active development, then there might not be much incentive to upgrade it. However, if an application requires ongoing maintenance, or new feature development including performance or security improvements, then you might consider upgrading the code for any of the following reasons:
 
@@ -30,7 +34,7 @@ If a legacy application is running satisfactorily, in a secure environment, and
 
 - Better standards conformance. The [/permissive-](../build/referencepermissive-standards-conformance.md) compiler option enables you to identify code that was formerly allowed by the Microsoft C++ compiler but does not conform to the current C++ standard.
 
-- Better run-time security, including features such as [guard checking](../build/reference/guard-enable-guard-checks.md) and address sanitizers (Visual Studio 2019 version 16.4).
+- Better run-time security, including more secure [C Runtime library]() features and compiler features such as [guard checking](../build/reference/guard-enable-guard-checks.md) and address sanitizers (Visual Studio 2019 version 16.4).
 
 - Modern static analysis tools, including the C++ Core Guidelines and Clang-Tidy, help identify potential problems in your source code.
 
diff --git a/docs/toc.yml b/docs/toc.yml
@@ -2842,7 +2842,7 @@
       href: porting/visual-cpp-change-history-2003-2015.md
     - name: Visual C++ What's New 2003 through 2015
       href: porting/visual-cpp-what-s-new-2003-through-2015.md
-    - name: C++ Binary Compatibility between 2015 and 2017
+    - name: C++ Binary Compatibility between 2015 and 2019
       href: porting/binary-compat-2015-2017.md
     - name: Overview of potential upgrade issues
       href: porting/overview-of-potential-upgrade-issues-visual-cpp.md
