Updated the guidance on updating SharePoint Framework packages (#970)

Author: waldekmastykarz

docs/spfx/update-latest-packages.md

@@ -5,18 +5,19 @@ ms.prod: sharepoint
 ---
 
 
-# Update SharePoint Framework packages 
+# Update SharePoint Framework packages
 
 SharePoint client-side development tools use the [npm](https://www.npmjs.com/) package manager to manage dependencies and other required JavaScript helpers. npm is typically included as part of Node.js setup.
 
-When you create a new client-side solution, the yeoman generator for SharePoint fetches the latest SharePoint Framework packages required for your client-side project. As you build your project, your existing packages could be outdated as there could be new versions of one or more packages available. Based on the [release notes](https://aka.ms/spfx-release-notes) for a particular release or the latest package, you may decide to update your SharePoint Framework packages used in your project. SharePoint Framework packages include both the npm packages you have installed in your project, for example: [@microsoft/sp-core-library](https://www.npmjs.com/package/@microsoft/sp-core-library), and npm packages installed globally, for example: [@microsoft/generator-sharepoint](https://www.npmjs.com/package/@microsoft/generator-sharepoint). 
+When you create a new client-side solution, the yeoman generator for SharePoint fetches the latest SharePoint Framework packages required for your client-side project. As you build your project, your existing packages could be outdated as there could be new versions of one or more packages available. Based on the [release notes](https://aka.ms/spfx-release-notes) for a particular release or the latest package, you may decide to update your SharePoint Framework packages used in your project. SharePoint Framework packages include both the npm packages you have installed in your project, for example: [@microsoft/sp-core-library](https://www.npmjs.com/package/@microsoft/sp-core-library), and npm packages installed globally, for example: [@microsoft/generator-sharepoint](https://www.npmjs.com/package/@microsoft/generator-sharepoint).
 
-While it may not be required, it is recommended you update the SharePoint Framework packages every so often so that you can get the latest changes and fixes that have been released. 
+While it may not be required, it is recommended you update the SharePoint Framework packages every so often so that you can get the latest changes and fixes that have been released.
 
 ## Find outdated packages in your project
-To find the outdated packages in your client-side project, including SharePoint Framework and other packages your project depends on, run the following command in a console in the same directory as your project. 
 
-```
+To find the outdated packages in your client-side project, including SharePoint Framework and other packages your project depends on, run the following command in a console in the same directory as your project.
+
+```sh
 npm outdated
 ```
 
@@ -30,69 +31,61 @@ The command will list the following information about the packages your project
 
 To identify the SharePoint Framework packages, look for the package names that start with the following npm scope and prefix:
 
-```
+```sh
 @microsoft/sp-
 ```
-Along with the framework packages, you may also need to update `react` and `office-ui-fabric-react` packages. Make sure you read the [release notes](https://aka.ms/spfx-release-notes) for that specific release to infer which packages require updates and plan accordingly.
 
-### Update packages
-To update one or more packages to the latest version, you will need to edit the package(s) information in the `package.json` file and then fetch the latest packages.
-
-#### Update package versions
-Open your project in your favorite code editor and locate the `package.json` file in the root of your project directory.
+Along with the framework packages, you may also need to update `react` and `office-ui-fabric-react` packages. Make sure you read the [release notes](https://aka.ms/spfx-release-notes) for that specific release to infer which packages require updates and plan accordingly.
 
-In the `package.json` file, locate the package(s) under the `dependencies` and `devDependencies` section and update the version to the latest version available that was listed in the `npm outdated` command. For example, the image below highlights the version updates to SharePoint Framework packages, the left section referring to the old and the right section referring to the latest package versions.
+### Using npm outdated with project targeting SharePoint 2016
 
-![Edit package versions in package.json file](../images/npm-update-packagejson-versions.png)
+Starting from Feature Pack 2, SharePoint 2016 supports SharePoint Framework solutions. SharePoint 2016 uses an older version of the SharePoint Framework, than the version available in SharePoint Online. When scaffolding new projects, the SharePoint Framework Yeoman generator prompts you to choose if your solution should be using the latest version of the SharePoint Framework and be working only with SharePoint Online or if it should use an older version of the SharePoint Framework and work with both SharePoint 2016 and SharePoint Online.
 
-Once you have updated the package versions, Save the `package.json` file.
+When you run the `npm outdated` command in a project targeting both SharePoint Online and SharePoint 2016, it will show you the latest versions of the SharePoint Framework packages. These versions however work only with SharePoint Online. If you would update your solution to use these latest packages, it would not work with SharePoint 2016 anymore.
 
-#### Update packages
-Open your favorite console and navigate to the root of your project directory. Follow the instructions below to successfully update the packages to its latest version.
+When working with SharePoint Framework solutions compatible with SharePoint hosted on-premises, you should always verify which patch level the target SharePoint farm has and which version of the SharePoint Framework it supports.
 
-Delete the `node_modules` folder. This is the folder where npm installs the packages locally for your project. Deleting this folder forces npm to fetch the latest and not duplicate existing packages.
+### Update packages
 
-If you are using a Mac or a Linux environment, then run the following command:
+When updating packages to newer versions, you should always use your package manager (npm or Yarn). You should not edit the `package.json` file manually. If you follow the recommended practice of using a lock file, your changes to the `package.json` file would be ignored.
 
-```
-rm -rf node_modules/
-```
+Start with identifying which packages need updating and which newer version you want to use. Please note, that it might not always be possible for you to use the latest version of the given package as it might be incompatible with other SharePoint Framework dependencies, such as TypeScript.
 
-If you are using a Windows environment, then run the following command:
+For each package that you want to update, run the following command:
 
-```
- rd /s /q node_modules/
+```sh
+npm install mypackage@newversion --save
 ```
 
-Now, execute the following command to fetch the latest packages from the npm registry:
+For example, if you were using AngularJS version v1.5.9 and wanted to update to version 1.6.5, you would run:
 
-```
-npm install
+```sh
+npm install [email protected] --save
 ```
 
-This command will create the `node_modules` folder and install all the packages your project depends on and its dependencies based on the information available in the `package.json` file. As we updated the file with the latest versions, npm will now have the latest packages and their dependencies installed. 
+Updating the package using npm will install the specified version of the package in your project, update the version number in the package.json file dependencies and the lock file used in your project.
 
 Once the packages are installed, execute the following command to clean up any old build artifacts:
 
-```
+```sh
 gulp clean
 ```
 
 ### Update your code
+
 Depending on breaking API changes, you may have to update your existing project code and config files. For each release, the [release notes](https://aka.ms/spfx-release-notes) will highlight any such breaking changes and the modifications required to your existing code. You will need to make sure you update your code with those fixes.
 
 You can always build the project to see if you have any errors and warnings by running the command in a console in your project directory:
 
-```
+```sh
 gulp build
 ```
 
 ## Update yeoman generator for SharePoint
-Unlike the npm packages that are installed to a specific client-side project, the yeoman generator for SharePoint is installed globally in your machine.
 
-To find if the yeoman generator for SharePoint is out of date, run the following command in a console window. 
+If you have installed the SharePoint Framework Yeoman generator globally, you can find out if it requires updating by running the following command:
 
-```
+```sh
 npm outdated -g
 ```
 
@@ -106,26 +99,20 @@ The command will list the following information about the packages installed glo
 
 To identify the generator package, look for the following package name:
 
-```
+```sh
 @microsoft/generator-sharepoint
 ```
 
 ### Update generator package
+
 Open your favorite console and execute the following command to update the generator to its latest published version:
 
-```
+```sh
 npm install @microsoft/generator-sharepoint@latest -g
 ```
 
-The command will update the yeoman generator for SharePoint to the latest published version along with its depedencies. You can validate this by executing the following command in the console:
+The command will update the yeoman generator for SharePoint to the latest published version along with its dependencies. You can validate this by executing the following command in the console:
 
-```
+```sh
 npm ls @microsoft/generator-sharepoint -g --depth=0
 ```
-
-
-
-
-
-
-