New docs (#2908)

CHANGELOG.md

@@ -1,5 +1,5 @@
 # CHANGELOG - sitespeed.io
-## 12.1.0 - UNRELEASED
+## 12.1.0 - 2020-03-03
 ### Added
 * Upgraded AXE-core from 3.4.1 -> 3.5.2 [#2879](https://github.com/sitespeedio/sitespeed.io/pull/2879)
 * Add budget for first party number of requests and transfer/content size [#2872](https://github.com/sitespeedio/sitespeed.io/pull/2872).

docs/_posts/2020-03-03-sitespeed.io-12.1-and-browsertime-8.1.md

@@ -0,0 +1,114 @@
+---
+layout: default
+title: sitespeed.io 12.1 and Browsertime 8.1.  
+description: A new sustainable web plugin created together with the Green Web Foundation and video/Visual Metrics support on OS X.
+authorimage: /img/aboutus/peter.jpg
+intro: A new sustainable web plugin created together with the Green Web Foundation and video/Visual Metrics support on OS X!
+keywords: sitespeed.io, browsertime, webperf
+image: https://www.sitespeed.io/img/sustainable-web.jpg
+nav: blog
+---
+
+# sitespeed.io 12.1 and Browsertime 8.1 
+
+In the new version of sitespeed.io, me (Peter) teamed up with [Chris Adams](https://twitter.com/mrchrisadams) of the [Green Web Foundation](https://www.thegreenwebfoundation.org) and we created a sustainable web plugin that makes it possible to calculate estimated carbon emission for a page.
+
+This release also makes it easier to run different WebDriver versions, easier support for MS Edge and video and visual metrics support on OS X!
+
+Read all about the new things here:
+- [The sustainable web plugin](#the-sustainable-web-plugin)
+    - [How to use it](#how-to-use-it)
+    - [The result](#the-result)
+    - [Extra configuration](#extra-configuration)
+- [Video and Visual Metrics on OS X](#video-and-visual-metrics-on-os-x)
+- [EdgeDriver automatically installed](#edgedriver-automatically-installed)
+- [Choose driver version](#choose-driver-version)
+- [And more](#and-more)
+
+## The sustainable web plugin
+
+<img src="{{site.baseurl}}/img/sustainable-web.jpg" class="pull-right img-big" alt="Sustainable web logo" width="176" height="269">
+
+We know using the internet means using electricity to power servers. And because most of that electricity comes from burning fossil fuels, it means every byte sent has a cost in carbon as well as power. The sustainable web plugin combines the latest in peer reviewed science and open data from the [Green Web Foundation](https://www.thegreenwebfoundation.org) to help you build greener, more sustainable websites and applications!
+
+We work out how much energy it takes to serve a site, then work out how much CO2 is emitted to generate the power needed that electricity, based on what information we have about where the power comes from. 
+
+[Chris Adams](https://twitter.com/mrchrisadams) has written down [more details](/documentation/sitespeed.io/sustainable/#the-slightly-longer-version) how we do the calculations.
+
+### How to use it
+
+Enable the plugin by adding `--sustainable.enable`:
+
+~~~bash
+docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:{% include version/sitespeed.io.txt %} https://www.sitespeed.io/ --sustainable.enable
+~~~
+
+### The result
+
+All data is produced under the new tab called  *Sustainable Web*.
+
+![Sustainable web tab]({{site.baseurl}}/img/sustainable-tab.png)
+{: .img-thumbnail}
+
+The plugin will use the transfer size of every asset and the domain (to know if the server run on green energy) and estimate the total amount of carbon emission for one page view.
+
+First you will see the amount of estimated carbon emission for one page view.
+
+![Estimated carbon emission per page view]({{site.baseurl}}/img/estimated-carbon.png)
+{: .img-thumbnail}
+
+But you can also add `--sustainable.pageViews` to your run and you will get the estimated carbon for that amount of page views. If you run it with  `--sustainable.pageViews 100000` you will get something like this:
+
+![Total carbon emission]({{site.baseurl}}/img/total-page-views-carbon.png)
+{: .img-thumbnail}
+
+Both the amount per page view and the total among will be automatically sent to Graphite/InfluxDB.
+
+We also categorise content per first/third party (with the `--firstParty` switch). You can see that for the site in this example the estimated carbon emission from third parties are over 79% of the total emission :(
+
+The next cut is per domain.
+
+![Carbon per domain]({{site.baseurl}}/img/carbon-per-domain.png)
+{: .img-thumbnail}
+
+<img src="{{site.baseurl}}/img/green-is-good.jpg" class="pull-right img-big" alt="Green is good" width="150" height="143">
+
+The green sign that says *green* means that that domain is marked as running on green energy in the Green Web Foundation database.
+
+We also produce a list of the top ten dirtiest assets on the page. The ones that produces most carbon emission.
+
+![Carbon per asset]({{site.baseurl}}/img/carbon-per-asset.png)
+{: .img-thumbnail}
+
+Here we have one JavaScript bundle that produces 39% of the total emission for that page. I wonder what kind of cool  functionality they have on the page? :)
+
+We also slice and dice the data per content type. This is interesting because it can help you take environment friendly decisions. For example for this website, having a specific font stands for over 50% of the estimated carbon emission for that page.
+
+![Carbon per content type]({{site.baseurl}}/img/carbon-content-type.png)
+{: .img-thumbnail}
+
+### Extra configuration
+
+By default the hosting data (knowing if a host is green) is collected from a local SQLite database included in sitespeed.io. You can use the Green Foundations API directly for the latest and fresh data using `--sustainable.useGreenWebHostingAPI`. That will generate a GET request to the API though.
+
+You can also disable the hosting match (all hosts will be treated as grey hosting) with `--sustainable.disableHosting`.
+
+## Video and Visual Metrics on OS X
+An old friend is back, we again support video and Visual Metrics on OS X! You need to install FFMpeg and the rest of the dependencies, checkout the [Travis-CI setup](https://github.com/sitespeedio/browsertime/blob/master/.travis.yml).
+
+We also a aim to make it possible to use video Visual Metrics on Windows and you can help us out in [Browsertime #1203](https://github.com/sitespeedio/browsertime/issues/1203)!
+
+## EdgeDriver automatically installed
+If you run on an OS that supports Edge, latest EdgeDriver will be automatically installed. If you want to skip installing, use *EDGEDRIVER_SKIP_DOWNLOAD=true* as an environment variable.
+
+## Choose driver version
+Since the ChromeDriver team decided that a ChromeDriver version needs to match a browser version, it has been more work to test other Chrome versions.
+
+You can download the ChromeDriver yourself from the [Google repo](https://chromedriver.storage.googleapis.com/index.html) and use ```--chrome.chromedriverPath``` to help Browsertime find it or you can choose which version to install when you install sitespeed.io with a environment variable: ```CHROMEDRIVER_VERSION=81.0.4044.20 npm install ```
+
+You can also choose versions for Edge and Firefox with `EDGEDRIVER_VERSION` and `GECKODRIVER_VERSION`.
+
+## And more
+We also done a couple of bug fixes. Checkout the  [Browsertime changelog](https://github.com/sitespeedio/browsertime/blob/master/CHANGELOG.md) and the [sitespeed.io changelog](https://github.com/sitespeedio/sitespeed.io/blob/master/CHANGELOG.md) for the full list. 
+
+/Peter

docs/documentation/sitespeed.io/browsers/index.md

@@ -134,7 +134,7 @@ You download ChromeDriver from [http://chromedriver.chromium.org](http://chromed
 You can run Safari on Mac OS X. To run on iOS you need Catalina and iOS 13. To see more what you can do with the SafariDriver you can run `man safaridriver` in your terminal.
 
 ### Limitations
-We do not support HAR, video, cookies/request headers in Safari at the moment.
+We do not support HAR, cookies/request headers in Safari at the moment.
 
 ### Configuration
 There are a couple of different specific Safari configurations.
@@ -166,10 +166,8 @@ The log file will be stored in **~/Library/Logs/com.apple.WebDriver/**.
 ## Edge
 You can use Chromium based MS Edge on the OS that supports it. At the moment this is experimental and we cannot guarantee that it works 100%.
 
-To get Egde to work you need to [download the webdriver yourself](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/). And then when you run point out the driver location:
-
 ~~~bash
-sitespeed.io -b edge --edge.edgedriverPath /path/to/the/msedgedriver https://www.sitespeed.io
+sitespeed.io -b edge https://www.sitespeed.io
 ~~~
 
 Edge use the exact same setup as Chrome (except the driver), so you use `--chrome.*` to configure Edge :) 
@@ -196,7 +194,7 @@ If you add your own complete check you can also choose when your check is run. B
 
 You can collect your own metrics in the browser by supplying JavaScript file(s). By default we collect all metrics inside [these folders](https://github.com/sitespeedio/browsertime/tree/master/browserscripts), but you might have something else you want to collect.
 
-Each javascript file need to return a metric/value which will be picked up and returned in the JSON. If you return a number, statistics will automatically be generated for the value (like median/percentiles etc).
+Each JavaScript file need to return a metric/value which will be picked up and returned in the JSON. If you return a number, statistics will automatically be generated for the value (like median/percentiles etc).
 
 For example say we have one file called scripts.js that checks how many scripts tags exist on a page. The script would look like this:
 
@@ -249,6 +247,19 @@ docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:{% include ve
 
 You can then download the tcp dump for each iteration and the SSL key log file from the result page.
 
+Packets will be written when the buffer is flushed. If you want to force packets to be written to the file when they arrive you can do that with `--tcpdumpPacketBuffered`.
+
+## WebDriver
+We use the WebDriver to drive the browser. We use [Chromedriver](https://chromedriver.chromium.org) for Chrome, [Geckodriver](https://github.com/mozilla/geckodriver/releases) for Firefox, [Edgedriver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver/) for Edge and [Safaridriver](https://developer.apple.com/documentation/webkit/testing_with_webdriver_in_safari) for Safari.
+
+When you install sitespeed.io/Browsertime we also install the latest released driver for Chrome, Edge and Firefox. Safari comes bundled with Safari driver. For Chrome the Chromedriver version needs to match the Chrome version. That can be annying if you want to test on old browsers, coming developer versions or on Android where that version hasn't been released yet.
+
+You can download the Chromedriver yourself from the [Google repo](https://chromedriver.storage.googleapis.com/index.html) and use ```--chrome.chromedriverPath``` to help Browsertime find it or you can choose which version to install when you install sitespeed.io with a environment variable: ```CHROMEDRIVER_VERSION=81.0.4044.20 npm install ```
+
+You can also choose versions for Edge and Firefox with `EDGEDRIVER_VERSION` and `GECKODRIVER_VERSION`.
+
+If you don't want to install the drivers you can skip them with `CHROMEDRIVER_SKIP_DOWNLOAD=true`, `GECKODRIVER_SKIP_DOWNLOAD=true` and `EDGEDRIVER_SKIP_DOWNLOAD=true`.
+
 ## How can I disable HTTP/2 (I only want to test HTTP/1.x)?
 In Chrome, you just add the switches <code>--browsertime.chrome.args disable-http2</code>.
 

docs/documentation/sitespeed.io/index.md

@@ -47,6 +47,7 @@ Sitespeed.io is the complete toolbox to test the web performance of your web sit
  * [Setup S3](s3/) - how to setup S3 for your html result/videos and screenshots.
  * [Setup GCS](gcs/) - how to setup Google Cloud storage (GCS) for your html result/videos and screenshots.
  * [Single Page Application](spa/) - how to test your single page application.
+ * [Sustainable web plugin](sustainable/) - the sustainable web plugin helps you build a greener, more sustainable websites and applications.
  * [Third party requests](thirdparty/) - keep track of those 3rd party scripts.
  * [Video](video/) - all that you can do with the video and filmstrip.
  * [WebPageReplay](webpagereplay/) - WebPageReplay is proxy that first records your web site and then replay it locally. That can help you find performance regression in the front-end code easier: Latency/server timings are constant.

docs/documentation/sitespeed.io/installation/index.md

@@ -65,7 +65,7 @@ yarn global add sitespeed.io
 We support Windows using [Docker](https://docs.docker.com/engine/installation/windows/). To be able to support running on Windows with NodeJS we need at least one [core contributor](/aboutus/) that can focus on Windows. Are you that one? Please [get in touch](https://github.com/sitespeedio/sitespeed.io/issues/new)!
 
 ### Skip installing ChromeDriver/GeckoDriver
-If you don't want to install ChromeDriver or GeckoDriver when you install through npm you can skip them with an environment variable.
+If you don't want to install ChromeDriver, EdgeDriver or GeckoDriver when you install through npm you can skip them with an environment variable.
 
 Skip installing ChromeDriver:
 
@@ -77,4 +77,10 @@ Skip installing GeckoDriver:
 
 ~~~bash
 GECKODRIVER_SKIP_DOWNLOAD=true npm install sitespeed.io -g
+~~~
+
+Skip installing EdgeDriver:
+
+~~~bash
+EDGEDRIVER_SKIP_DOWNLOAD=true npm install sitespeed.io -g
 ~~~

docs/documentation/sitespeed.io/sustainable/index.md

@@ -0,0 +1,113 @@
+---
+layout: default
+title: Build a sustainable web
+description: Use the sustainable plugin to measure and keep track of your carbon cost.
+keywords: sustainable, web, carbon, sitespeed.io
+nav: documentation
+category: sitespeed.io
+image: https://www.sitespeed.io/img/sustainable-web.jpg
+twitterdescription: Build a sustainable web using the sustainable plugin.
+---
+
+[Documentation]({{site.baseurl}}/documentation/sitespeed.io/) / Sustainable web plugin
+
+# Sustainable web plugin
+{:.no_toc}
+
+<img src="{{site.baseurl}}/img/sustainable-web.jpg" class="pull-right img-big" alt="Sustainable web logo" width="176" height="269">
+
+We know using the internet means using electricity to power servers. And because most of that electricity comes from burning fossil fuels, it means every byte sent has a cost in carbon as well as power. The sustainable web plugin combines the latest in peer reviewed science and open data from the [Green Web Foundation](https://www.thegreenwebfoundation.org) to help you build greener, more sustainable websites and applications!
+
+We work out how much energy it takes to serve a site, then work out how much CO2 is emitted to generate the power needed that electricity, based on what information we have about where the power comes from. 
+
+[Chris Adams](https://twitter.com/mrchrisadams) has written down [more details](/documentation/sitespeed.io/sustainable/#the-slightly-longer-version) how we do the calculations.
+
+* Lets place the TOC here
+{:toc}
+
+### How to use it
+
+Enable the plugin by adding `--sustainable.enable`:
+
+~~~bash
+docker run --rm -v "$(pwd)":/sitespeed.io sitespeedio/sitespeed.io:{% include version/sitespeed.io.txt %} https://www.sitespeed.io/ --sustainable.enable
+~~~
+
+### The result
+
+All data is produced under the new tab called  *Sustainable Web*.
+
+![Sustainable web tab]({{site.baseurl}}/img/sustainable-tab.png)
+{: .img-thumbnail}
+
+The plugin will use the transfer size of every asset and the domain (to know if the server run on green energy) and estimate the total amount of carbon emission for one page view.
+
+First you will see the amount of estimated carbon emission for one page view.
+
+![Estimated carbon emission per page view]({{site.baseurl}}/img/estimated-carbon.png)
+{: .img-thumbnail}
+
+But you can also add `--sustainable.pageViews` to your run and you will get the estimated carbon for that amount of page views. If you run it with  `--sustainable.pageViews 100000` you will get something like this:
+
+![Total carbon emission]({{site.baseurl}}/img/total-page-views-carbon.png)
+{: .img-thumbnail}
+
+Both the amount per page view and the total among will be automatically sent to Graphite/InfluxDB.
+
+We also categorise content per first/third party (with the `--firstParty` switch). You can see that for the site in this example the estimated carbon emission from third parties are over 79% of the total emission :(
+
+The next cut is per domain.
+
+![Carbon per domain]({{site.baseurl}}/img/carbon-per-domain.png)
+{: .img-thumbnail}
+
+The green sign that says *green* means that that domain is marked as running on green energy in the Green Web Foundation database.
+
+We also produce a list of the top ten dirtiest assets on the page. The ones that produces most carbon emission.
+
+![Carbon per asset]({{site.baseurl}}/img/carbon-per-asset.png)
+{: .img-thumbnail}
+
+Here we have one JavaScript bundle that produces 39% of the total emission for that page. I wonder what kind of cool  functionality they have on the page? :)
+
+We also slice and dice the data per content type. This is interesting because it can help you take environment friendly decisions. For example for this website, having a specific font stands for over 50% of the estimated carbon emission for that page.
+
+![Carbon per content type]({{site.baseurl}}/img/carbon-content-type.png)
+{: .img-thumbnail}
+
+### Extra configuration
+
+By default the hosting data (knowing if a host is green) is collected from a local SQLite database included in sitespeed.io. You can use the Green Foundations API directly for the latest and fresh data using `--sustainable.useGreenWebHostingAPI`. That will generate a GET request to the API though.
+
+You can also disable the hosting match (all hosts will be treated as grey hosting) with `--sustainable.disableHosting`.
+
+## How it works
+
+### Short version 
+
+We work out how much energy it takes to serve a site, then work out how much CO2 is emitted to generate the power needed that electricity, based on what information we have about where the power comes from.
+
+### The slightly longer version
+
+#### First, work out the energy needed
+We work out how much energy it takes to serve a site, based on the 1byte model published by The Shift project in their report [Lean ICT: for a sober digital](https://theshiftproject.org/en/lean-ict-2/).
+
+This in turn draws numbers from the paper [Projecting the chiaroscuro of the electricity use of communication and computing from 2018 to 2030](https://www.researchgate.net/publication/331047520_Projecting_the_chiaroscuro_of_the_electricity_use_of_communication_and_computing_from_2018_to_2030). This is the most recent peer reviewed number we could find providing in format offering a breakdown of energy use broken down by data centre, data transfer and device usage. When we find a more recent up-to-date model, offering a similar breakdown we will update the plugin to use it.
+
+While the 1byte model also includes the energy usage for the production and use of devices, device we do not include this in our calculations. We do this for a number of reasons:
+
+The first is that devices use power differently viewing a website or application compared when continuously downloading video for viewing. This is acknowledged in The Shift Project's own report.
+
+The second is that the sitespeed.io plugin is intended to help people realise that performance budgets can also be carbon budgets, and they can make measurable steps to improve the climate impact of digital services, through changes in how they are made.
+
+Third, the majority of the carbon emissions from a device come from the actual production of a smartphone or laptop, not the use. While thoughtful design choices can make it possible to run applications and websites on older hardware, it's much more difficult to measure how these changes in design affect the climate impact without collecting further information about the end user's devices. This is possible with analytics tools like Matomo, but this goes beyond the scope of this plugin.
+
+#### Estimating carbon for this energy
+
+Once we have the estimated energy usage needed to serve a site, we then need to work out the emissions from this energy one for conventional, 'grey' power, and one for renewable green power.
+
+Larger data centres have historically been cited close to sources of cheap power, available around the clock, which would usually come from fossil fuels previously. This often results in an [energy mix tends to be dirtier than average](https://the-beam.com/energy/how-weve-made-the-web-dirty/), so we use the Shift Project's figure of 519 grams of CO2 per kilowatt hour.
+
+For the rest of the internet, we use the [International Energy Agency's](https://hyp.is/MPRiUlTMEeq13bM-WjChjQ/www.iea.org/reports/global-energy-co2-status-report-2019/emissions) figure from of 475g of CO2 per kilowatt hour for for 2018, as an average across the globe.
+
+Where we know power is generated using renewables we use the figure from the UK's regulator Ofgem, for renewables including solar, wind and hydroelectricity, of 33.4 grammes of CO2 per kilowatt hour. To tell how a site is powered, we look up the domain with the Green Web Foundation's - either via the their API, or when available, using their publicly available [url2green](https://www.thegreenwebfoundation.org/green-web-datasets/) dataset.

docs/documentation/sitespeed.io/video/index.md

@@ -17,13 +17,11 @@ twitterdescription: Use the video in sitespeed.io
 {:toc}
 
 ## The stack (easy with Docker)
-We use FFMpeg to record a video with 30 fps of the screen (but you can configure the number of frames per second). The easiest way is to use our Docker container with pre-installed FFMpeg but if you for some reason want to use the npm version, you can record a video too. As long as you install FFMpeg yourself.
+We use FFMpeg to record a video with 30 fps of the screen (but you can configure the number of frames per second). The easiest way is to use our Docker container with pre-installed FFMpeg and if you use the npm version, you can record a video too. Video works on Linux and OS X at the moment.
 
-When we got the video we use [Visual Metrics](https://github.com/WPO-Foundation/visualmetrics) (built by Pat Meenan) to analyse the video and get SpeedIndex and other visual metrics from the video. If you use our Docker container you get that for free, else you need to install all the [Visual Metrics dependencies](https://github.com/sitespeedio/docker-visualmetrics-deps/blob/master/Dockerfile) yourself.
+When we got the video we use [Visual Metrics](https://github.com/WPO-Foundation/visualmetrics) (built by Pat Meenan) to analyse the video and get SpeedIndex and other visual metrics from the video. If you use our Docker container you get that for free, else you need to install all the [Visual Metrics dependencies](https://github.com/sitespeedio/browsertime/blob/master/.travis.yml) yourself. You need FFMPeg, ImageMagick and a couple Pythin libraries. Checkout Browsertimes [Travis-CI configuration](https://github.com/sitespeedio/browsertime/blob/master/.travis.yml) to see what's needed.
 
-We record the video in two steps: First we turn the background orange (that is used by VisualMetrics to know when
- the navigation starts), sets the background to white and let the browser go to the URL. The video is recorded
- lossless and then when the video has been analysed, we remove the orange frames and convert the video to a compressed mp4.
+We record the video in two steps: First we turn the background orange (that is used by VisualMetrics to know when the navigation starts), sets the background to white and let the browser go to the URL. The video is recorded lossless and then when the video has been analysed, we remove the orange frames and convert the video to a compressed mp4.
 
 The video will look something like this:
 
@@ -71,8 +69,7 @@ If you run the Docker container we will automatically setup XVFB as a virtual fr
 ### Collect visual elements metrics
 You can choose to collect when visual elements are visible (and on their final position) on the screen. Turn on with <code>--visualElement</code> and collect Visual Metrics from elements. Works only with <code>--visualMetrics</code> turned on (default in Docker). By default you will get visual metrics from the largest image within the view port and the largest H1. 
 
-You can also configure to pickup your own defined elements with <code>--scriptInput.visualElements</code>. Give the element a name
-and select it with <code>document.body.querySelector</code>. Use it like this: <code>--scriptInput.visualElements name:domSelector</code> . Add multiple instances to measure multiple elements. Visual Metrics will use these elements and calculate when they are visible and fully rendered. These metrics will also be included in HAR file so you can look at the waterfall and see when elements are visual within the viewport.
+You can also configure to pickup your own defined elements with <code>--scriptInput.visualElements</code>. Give the element a name and select it with <code>document.body.querySelector</code>. Use it like this: <code>--scriptInput.visualElements name:domSelector</code> . Add multiple instances to measure multiple elements. Visual Metrics will use these elements and calculate when they are visible and fully rendered. These metrics will also be included in HAR file so you can look at the waterfall and see when elements are visual within the viewport.
  
 
  ![Visual elements in Graphite]({{site.baseurl}}/img/visual-elements-graphite.png)