merge conflicts

Gemfile.lock

@@ -13,9 +13,9 @@ GEM
       execjs
     coffee-script-source (1.11.1)
     colorator (1.1.0)
-    commonmarker (0.17.11)
+    commonmarker (0.17.13)
       ruby-enum (~> 0.5)
-    concurrent-ruby (1.0.5)
+    concurrent-ruby (1.1.3)
     dnsruby (1.61.2)
       addressable (~> 2.5)
     em-websocket (0.5.1)
@@ -25,20 +25,20 @@ GEM
       ffi (>= 1.3.0)
     eventmachine (1.2.7)
     execjs (2.7.0)
-    faraday (0.15.2)
+    faraday (0.15.4)
       multipart-post (>= 1.2, < 3)
     ffi (1.9.25)
     forwardable-extended (2.6.0)
     gemoji (3.0.0)
-    github-pages (191)
+    github-pages (193)
       activesupport (= 4.2.10)
       github-pages-health-check (= 1.8.1)
-      jekyll (= 3.7.3)
+      jekyll (= 3.7.4)
       jekyll-avatar (= 0.6.0)
       jekyll-coffeescript (= 1.1.1)
       jekyll-commonmark-ghpages (= 0.1.5)
       jekyll-default-layout (= 0.1.4)
-      jekyll-feed (= 0.10.0)
+      jekyll-feed (= 0.11.0)
       jekyll-gist (= 1.5.0)
       jekyll-github-metadata (= 2.9.4)
       jekyll-mentions (= 1.4.1)
@@ -81,13 +81,13 @@ GEM
       octokit (~> 4.0)
       public_suffix (~> 2.0)
       typhoeus (~> 1.3)
-    html-pipeline (2.8.4)
+    html-pipeline (2.9.1)
       activesupport (>= 2)
       nokogiri (>= 1.4)
     http_parser.rb (0.6.0)
     i18n (0.9.5)
       concurrent-ruby (~> 1.0)
-    jekyll (3.7.3)
+    jekyll (3.7.4)
       addressable (~> 2.4)
       colorator (~> 1.0)
       em-websocket (~> 0.5)
@@ -114,7 +114,7 @@ GEM
       rouge (~> 2)
     jekyll-default-layout (0.1.4)
       jekyll (~> 3.0)
-    jekyll-feed (0.10.0)
+    jekyll-feed (0.11.0)
       jekyll (~> 3.3)
     jekyll-gist (1.5.0)
       octokit (~> 4.2)
@@ -185,7 +185,7 @@ GEM
       jekyll-seo-tag (~> 2.0)
     jekyll-titles-from-headings (0.5.1)
       jekyll (~> 3.3)
-    jekyll-watch (2.0.0)
+    jekyll-watch (2.1.2)
       listen (~> 3.0)
     jemoji (0.10.1)
       gemoji (~> 3.0)
@@ -206,11 +206,11 @@ GEM
       jekyll-seo-tag (~> 2.1)
     minitest (5.11.3)
     multipart-post (2.0.0)
-    nokogiri (1.8.4)
+    nokogiri (1.8.5)
       mini_portile2 (~> 2.3.0)
-    octokit (4.10.0)
+    octokit (4.13.0)
       sawyer (~> 0.8.0, >= 0.5.3)
-    pathutil (0.16.1)
+    pathutil (0.16.2)
       forwardable-extended (~> 2.6)
     public_suffix (2.0.5)
     rb-fsevent (0.10.3)
@@ -220,9 +220,9 @@ GEM
     ruby-enum (0.7.2)
       i18n
     ruby_dep (1.5.0)
-    rubyzip (1.2.1)
+    rubyzip (1.2.2)
     safe_yaml (1.0.4)
-    sass (3.5.7)
+    sass (3.7.2)
       sass-listen (~> 4.0.0)
     sass-listen (4.0.0)
       rb-fsevent (~> 0.9, >= 0.9.4)
@@ -233,7 +233,7 @@ GEM
     terminal-table (1.8.0)
       unicode-display_width (~> 1.1, >= 1.1.1)
     thread_safe (0.3.6)
-    typhoeus (1.3.0)
+    typhoeus (1.3.1)
       ethon (>= 0.9.0)
     tzinfo (1.2.5)
       thread_safe (~> 0.1)

_includes/header.html

@@ -1,7 +1,7 @@
 <header id="page-header" role="banner">
 	<div class="page-header-content">
 		<a href="{{ site.baseurl }}" class="logo-link">10up</a>
-		<nav class="page-nav top-nav" role="navigation" aria-label="main-navigation">
+		<nav id="top" class="page-nav top-nav" role="navigation" aria-label="main-navigation">
 			<ul class="header-nav nav-dropdowns js-mobile-expandable">
 				{% assign pages_list = site.pages | sort: "weight" %}
 				{% assign group = 'navigation' %}

_includes/markdown/JavaScript.md

@@ -171,6 +171,41 @@ On all new projects you should be using up to date JavaScript methodologies comb
 
 Some older projects that have not yet been upgraded may not have the capability to use the most modern techniques, but it is still important to have processes in place that allow us to grow the technology stack as a project matures. In these cases, you should still follow best practice recommendations even if the newest patterns are not yet available to you.
 
+### Secure Your Code
+
+In JavaScript, we often have to insert new elements with dynamic attributes and content into the DOM. A common way to do this is to use the [```innerHTML```](https://developer.mozilla.org/en-US/docs/Web/API/Element/innerHTML) method like so:
+
+```javascript
+const someElement = document.getElementById( 'someElement' );
+const someUrl = 'https://someurl.com/';
+const someContent = 'Some content';
+
+someElement.innerHTML = `<div class="container"><a href="${ someUrl }">${ someContent }</a></div>`;
+```
+
+However, passing HTML strings to ```innerHTML``` and methods like it can expose your code to [cross-site scripting](https://developer.mozilla.org/en-US/docs/Glossary/Cross-site_scripting), also known as XSS—the most common security vulnerability in JavaScript. Because these methods evaluate strings passed to them as HTML, they can execute potentially harmful code. For instance, if ```someContent``` in the above example is ```<img src="fakeImage" onerror="alert( 'hacked!' )" />```, the JavaScript in the ```onerror``` attribute will be executed.
+
+There are several measures you can take to circumvent this XSS vulnerability:
+
+#### Use ```textContent``` instead of ```innerHTML```
+
+When setting the human-readable content of a single element, using ```textContent``` is safer than using ```innerHTML``` because it does not parse strings as HTML—meaning any malicious code passed to it will not be executed. Refer to [MDN's documentation on ```textContent```](https://developer.mozilla.org/en-US/docs/Web/API/Node/textContent) for more info.
+
+#### Use the ```DOM``` API to create and add elements
+
+When you need to create multiple DOM elements, use the ```document.createElement``` method to create new elements and the ```Element``` API to set attributes and append them to the document. Creating your own elements and attributes will ensure that only those you explicitly define will make their way into the DOM.
+
+Note that appending new elements to the DOM is a relatively expensive operation, so in general you'll want to build out the structure of new elements _before_ adding them to the DOM, preferably within a single container element, then append them to the document all at once.
+
+Refer to MDN's documentation on [```document.createElement```](https://developer.mozilla.org/en-US/docs/Web/API/Document/createElement) and the [```Element``` API](https://developer.mozilla.org/en-US/docs/Web/API/Element) for more info.
+
+#### Sanitize HTML strings before adding to the DOM
+
+In general, using the ```Element``` API is the preferred best practice to safely create and add DOM elements. However, it tends to result in much more verbose code compared to HTML-parsing methods like ```innerHTML```. This can become painful if you need to dynamically create a large number of new elements. In these cases, the convenience of methods like ```innerHTML``` can be extremely tempting. 
+
+If you need to generate a large amount of HTML dynamically, consider using a ```DOMParser``` to parse and sanitize HTML strings before adding the HTML to the DOM with a method like ```innerHTML```. Parsing HTML strings with a ```DOMParser``` will not automatically make the code any safer, but it will allow you to access the elements from the string and strip potentially unsafe tags and attributes before they have a chance to get executed. Refer to [MDN's documentation on ```DOMParser```](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser) for more info.
+
+Alternatively, you may consider adding a client-side sanitization library to your project so you can strip potentially malicious code from your HTML before you add it to the DOM. Passing your HTML strings through a sanitizer can help prevent XSS attacks when using methods like ```innerHTML```. However, no library is perfect, so be aware that you are relying on the security of the sanitizer you choose. Also remember to consider the effect on [performance](#performance) when deciding whether to add any large library to your project.
 
 <h2 id="code-style" class="anchor-heading">Code Style & Documentation {% include Util/top %}</h2>
 
@@ -197,4 +232,6 @@ There are many JavaScript libraries available today. Many of them directly compe
 
 [React](https://reactjs.org/) - Using React provides a library to create large-scale, stateful JavaScript applications. It aims to provide a flexible system of creating highly componentized user interfaces. [Learn more about how we use React]({{ site.baseurl }}/react).
 
+[Vue](https://vuejs.org/) - Implementing Vue on a project allows us to take advantage of the statefulness built into something like React, but apply it on a much more lightweight and smaller scale as to not bog down performance by loading in a heavy library. [Learn more about how we use Vue]({{ site.baseurl }}/vue).
+
 [Backbone](http://backbonejs.org) - Provides a framework for building complex JavaScript applications. Backbone is based on the usage of models, views, and collections. WordPress core relies heavily on Backbone especially in the media library. Backbone requires Underscore and a DOM manipulation library.

_includes/markdown/Structure.md

@@ -54,19 +54,49 @@ The `JS` folder is described separately, below to improve readability:
 |    |- shared/ __________________________ # Shared JS between the admin and front end
 ```
 
-<h2 id="dependencies" class="anchor-heading">Dependencies {% include Util/top %}</h2>
+<h2 id="dependencies" class="anchor-heading">Dependencies and Package Management {% include Util/top %}</h2>
 
 Projects generally use two different types of dependency management:
 
 - [npm](https://npmjs.org) is used to manage relevant dependencies.
 - [Composer](https://getcomposer.org) is used primarily for back-end (i.e. admin or PHP-based) dependencies
 
-Generally, dependencies pulled in via a manager are _not_ committed to the repository, just the file defining the dependencies. This allows all developers involved to pull down local copies of each library as needed, and keeps the repository fairly clean.
+## When and How to Use Packages
+
+When choosing a third-party library for inclusion in your project, see if it’s available on npm (JavaScript) or Packagist (PHP). Additionally, WordPress plugins and themes are often available on [wppackagist.org](wppackagist.org). Retrieving dependencies from a package repo helps slim down the code in our version control repos, meaning there’s less we need to retrieve when a new engineer starts on a project. It also contributes to easily keeping code up to date with security and performance improvements.
+
+Most package managers differentiate between dependencies and devDependencies:
+
+- devDependencies are code, often build tools like Webpack or Gulp, needed to get a site to a production-ready state.
+- Dependencies are code actually used in the functioning of the site, like Lodash or Normalize.css.
+
+Existing projects that weren’t built with package managers in mind offer an opportunity for engineering teams to implement them for all new development. Teams should also estimate and plan around the time needed to retrofit the existing codebase.
 
 With some projects, using an automated dependency manager won't make sense. In server environments like VIP, running dependency software on the server is impossible. If required repositories are private (i.e. invisible to the clients' in-house developers), expecting the entire team to use a dependency manager is unreasonable. In these cases, the dependency, its version, and the reason for its inclusion in the project outside of a dependency manager should be documented.
 
 If you are using a package where the naming and usage isn't obvious to the average engineer, be sure to document its purpose in the README, style guide, or project documentation.
 
+## Selecting Packages
+
+Packages are often a Matryoshka of their own dependencies. Though this code is almost certainly all open source, it’s not practical to apply the same scrutiny to packages’ code as is expected before selecting WordPress themes and plugins. Effective package selection, therefore, relies on other factors that engineers can quickly evaluate:
+
+- Is the package actively developed and supported?
+- Does the package have a solid reputation in the community?
+- How frequently have security issues been reported, and how quickly have they historically been addressed?
+- Does the package require a small number of dependencies?
+- How easily could the packages’ code be forked in case it’s abandoned or a critical issue needs to be addressed right away? When evaluating this, consider the package’s open source license along with the ease of modifying the code.
+
+## Package Versions and Lock 
+
+When installing a package, engineers can specify a version string the package manager uses to select an appropriate package version. Never specify an exact x.y.z version or else security, performance, and functionality upgrades won’t be available.	
+Most third-party packages follow the Semantic Versioning (semver.org) system, where packages’ version numbers are defined in terms of major, minor, and patch levels. Changes to semver-compliant packages are expected to trigger a new major version when breaking backward compatibility.
+
+Instead of a full x.y.z version, Specify major & minor versions x.y to minimize the risk of breaking changes being introduced into your project. Start version number strings with a caret (^) for most dependencies, for example ^1.2
+
+For dependencies that don’t use semver, like many WordPress themes and plugins, engineers should still specify major and minor versions x.y. Start version numbers with a tilde (~) for most dependencies.
+
+Modern package managers create lock files, such as npm’s “package-lock.json” and Composer’s “composer.lock”. These files record the package versions each package manager chose to satisfy the version number constraints on the current version of the platform. Lock files should be committed to project version control repos so all engineers can be on the same page.
+
 ## Composer Based Project Structure
 
 Here's how we might structure a project with Composer:

_includes/markdown/Tools.md

@@ -2,11 +2,9 @@ The following are tools we use at 10up. This list will grow and change over time
 
 <h2 id="local-development" class="anchor-heading">Local Development Environments {% include Util/top %}</h2>
 
-At 10up, we use [Vagrant](https://www.vagrantup.com/) and/or [Docker](https://www.docker.com/) to build and interact with virtual environments that match production as closely as possible. There are many setups and configurations available. The following setups are the only ones we support internally.
+At 10up, we use [Docker](https://www.docker.com/) to build and interact with virtual environments that match production as closely as possible. There are many setups and configurations available, but the following setup is supported internally:
 
-[Varying Vagrant Vagrants (VVV)](https://github.com/Varying-Vagrant-Vagrants/VVV) - Our standard Vagrant setup for client sites and local development. This was originally a 10up project (now open-sourced) and something with which we have a lot of familiarity.
-
-[WP Local Docker](https://github.com/10up/wp-local-docker) - A simple Docker-based development environment. This setup is great because it's very easy to setup, simple to interact with, and makes standardizing package versions (i.e. PHP) extremely easy.
+* [WP Local Docker](https://10up.github.io/wp-local-docker-docs/) - An easy-to-use Docker-based local development environment for WordPress development that works on Mac, Windows, and Linux. Each environment within WP Local Docker is powered by Nginx, PHP-FPM, Memcached, and if desired, ElasticSearch.
 
 <h2 id="scaffolding" class="anchor-heading">Scaffolding {% include Util/top %}</h2>
 
@@ -34,9 +32,9 @@ When a WordPress install is managed and maintained by an engineering team, and w
 
 <h2 id="command-line" class="anchor-heading">Command Line Tools {% include Util/top %}</h2>
 
-[WP-CLI](https://wp-cli.org) - A command line interface for WordPress. This is an extremely powerful tool that allows us to do imports, exports, run custom scripts, and more via the command line. Often this is the only way we can affect a large database (WordPress.com VIP or WP Engine). This tool is installed by default on [VVV](https://github.com/Varying-Vagrant-Vagrants/VVV) and [WP Local Docker](https://github.com/10up/wp-local-docker).
+[WP-CLI](https://wp-cli.org) - A command line interface for WordPress. This is an extremely powerful tool that allows us to do imports, exports, run custom scripts, and more via the command line. Often this is the only way we can affect a large database (WordPress.com VIP or WP Engine). This tool is installed by default on [WP Local Docker](https://10up.github.io/wp-local-docker-docs/).
 
-<h3 id="a11y-testing" class="anchor-heading">Accessibility Testing</h3>
+<h2 id="a11y-testing" class="anchor-heading">Accessibility Testing {% include Util/top %}</h2>
 
 We use a variety of tools to test our sites for accessibility issues. WebAim has some great resources on [how to evaluate sites](http://webaim.org/articles/screenreader_testing/) with a screen reader.
 

_includes/markdown/Version-Control.md

@@ -2,7 +2,7 @@ We version control all projects at 10up using [Git](https://git-scm.com/). Versi
 
 <h2 id="structure-package-management" class="anchor-heading">Structure and Package Management{% include Util/top %}</h2>
 
-We structure our projects in such a way that we are not version controlling third party code, rather, they are included via a package manager. For PHP, we use [Composer](https://getcomposer.org/) to manage PHP dependencies (also see package managers](/Engineering-Best-Practices/tools/#package-managers)) e.g. WordPress core itself, plugins, and themes. Dependency management structuring is explained more in the [Structure](https://10up.github.io/Engineering-Best-Practices/structure/#composer-based-project-structure) section.
+We structure our projects in such a way that we are not version controlling third party code, rather, they are included via a package manager. For PHP, we use [Composer](https://getcomposer.org/) to manage PHP dependencies (also see [package managers](/Engineering-Best-Practices/tools/#package-managers)) e.g. WordPress core itself, plugins, and themes. Dependency management structuring is explained more in the [Structure](https://10up.github.io/Engineering-Best-Practices/structure/#composer-based-project-structure) section.
 
 We also do not commit compiled files (JS/CSS). This saves us from having to deal with people forgetting to compile files and large merge conflicts. Instead we generate compile files during deployment.