V6

.eslintignore

@@ -4,7 +4,6 @@ webExtensionApis/study/api.js
 webExtensionApis/study/stubApi.js
 package-lock.json
 # do not lint/format bundled util libraries
-test-addon/src/privileged/prefs/
 test-addon/src/privileged/study/
 # makes sure that eslintrc.js gets linted/formatted
 !.eslintrc.js

.spelling

@@ -143,8 +143,8 @@ studyInfo
 studyInfoObject
 studyName
 studySetup
-studyType
-studyTypesEnum
+telemetryPipeline
+telemetryPipelinesEnum
 StudyUtils
 studyUtils
 StudyUtils.jsm

README.md

@@ -1,114 +1,46 @@
-| [WebExtensions API:s](./docs/api.md) | [Small example](./examples/small-study/) | [(Full) WebExtension template](https://github.com/mozilla/shield-studies-addon-template/) | [Engineering your add-on](#engineering-your-own-study-add-on) | [Shield - Mozilla Wiki](https://wiki.mozilla.org/Firefox/Shield) |
-| ------------------------------------ | ---------------------------------------- | ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------- |
+| [WebExtensions API:s](./docs/api.md) | [Engineering your add-on](#engineering-your-own-study-add-on) |
+| ------------------------------------ | ------------------------------------------------------------- |
 
 
 # Shield Studies Add-on Utils
 
 [![CircleCI badge](https://img.shields.io/circleci/project/github/mozilla/shield-studies-addon-utils/master.svg?label=CircleCI)](https://circleci.com/gh/mozilla/shield-studies-addon-utils/)
 
+## Features
+
 This is the home of the [`shield-studies-addon-utils` npm package](https://www.npmjs.com/package/shield-studies-addon-utils), which provides:
 
-* WebExtensionExperiment API's
+### `shield-study` telemetry
+
+Validate and send `shield-study`, `shield-study-addon` Telemetry, allowing experiments to submit experiment-scoped stringified key-value pairs that are directly available for analysis.
 
-  * `browser.study`
+### Pioneer telemetry
 
-* Additional useful testing interface
+Validate, encrypt and send `shield-study`, `shield-study-addon` Pioneer Telemetry.
 
-  * `browser.studyDebug`
+### Other telemetry helpers
 
-* Scripts:
+Validate telemetry payloads against JSON schemas and calculate the size of a ping before submitting it.
 
-  * `copyStudyUtils` shell command copying these files in your study add-on.
+### Add-on test helpers
 
-## Goals:
+Helper classes and methods to write Selenium-based functional/unit tests for your study add-on.
 
-Allows writing [Shield and Pioneer Add-on Experiments](https://mana.mozilla.org/wiki/display/FIREFOX/Pref-Flip+and+Add-On+Experiments) that manage their own life-cycle.
+### Survey URLs helper
 
-* **assign variations**: deterministic, persistent variation assignments for A/B multi-variant studies.
-* **startup/shutdown/disable/uninstall**: has strong opinions about business logic for Telemetry around startup, shutdown
-* **expiration**: helps handle study expiration by storing first run timestamp in a preference
-* **eligibility**: consistent handling of post-install / first run eligiblity
-* **telemetry helpers** make it easier to send correctly formatted `shield-study`, `shield-study-addon` Telemetry.
-* **format survey URLs** and other 'post' and 'mid-study' URLs to have correct appended query arguments, to
-  * create flow-control logic during surveys
-  * proper version, study and other tracking variables
+For formatting 'post' and 'mid-study' survey URLs to have correct appended query arguments in the format that matches the corresponding SurveyGizmo library elements
 
 ## Help and support
 
 Thinking about building a Study Add-on? Please read [the docs on Pref-Flip and Add-On Experiments](https://mana.mozilla.org/wiki/display/FIREFOX/Pref-Flip+and+Add-On+Experiments) first.
 
-If you haven't checked out [the template](https://github.com/mozilla/shield-studies-addon-template) yet, do it. It contains a lot of best practices that helps study add-ons pass QA quicker.
-
-## Learn the API
-
-1.  **Read** the API: [study api.md](./docs/api.md)
-
-    Documentation of the API. Notice that there are
-
-    * `functions`: async functions in the `browser.study`.
-    * `events`: webExtension events in the `browser.study`
-    * `types`: jsonschema draft-04 formats.
-
-2.  **Explore** [`examples/small-study`](./examples/small-study/):
-
-    * [`manifest.json`](./examples/small-study/src/manifest.json)
-
-      Notice the `experiment_apis` section. This maps `browser.study` to the privileged API code. (See details below)
-
-    * [`studySetup.js`](./examples/small-study/src/studySetup.js)
-
-      Construct a `studySetup` usable by `browser.study.setup`
-
-    * [`background.js`](./examples/small-study/src/background.js)
-
-      Using the `browser.study` API within a small instrumented feature.
-
-3.  **Create magic** using [mozilla/shield-studies-addon-template/](https://github.com/mozilla/shield-studies-addon-template/) to get started with an example study where `shield-studies-addon-utils` is already installed and configured.
-
-## Installing the Shield Studies Add-on Utils in your add-on
-
-1.  Install the Package
-
-    ```sh
-    npm install --save shield-studies-addon-utils
-    ```
-
-2.  Copy the files to your 'privileged' src directory
-
-    ```sh
-    # copyStudyUtils is installed in `node_modules/.bin`
-    copyStudyUtils ./privileged --example
-    ```
-
-    Suggestion: make this part of your `package.json:scripts.postinstall` script.
-
-3.  Set logging in `about:config`
-
-    ```
-    prefName: shieldStudy.logLevel
-    values: All|Trace|Debug|Info|Warn|Error
-    ```
+## Installing Shield Studies Add-on Utils in your add-on
 
-Again, [the template](https://github.com/mozilla/shield-studies-addon-template) has this preconfigured already.
-
-## WebExtension APIs Provided by Shield Studies Add-on Utils
-
-### `browser.study.*`
-
-[`browser.study` API documentation](./webExtensionApis/study/api.md)
-
-Provides these capabilities:
-
-1.  **deterministically decide variation for a client** (`setup`), i.e. based on a hash of non-PII user info, they will always get assigned to the same branch every time the study launches)
-2.  **Report study lifecycle data** using Telemetry configured.
-3.  **Report feature interaction and success data** using study-specific Telemetry (`sendTelemetry`).
-4.  **Registers/unregisters the study as an active experiment** (By annotating the Telemetry Environment, marking the user as special in the `main` ping).
-5.  **Validates setup using schema for study configuration**.
-6.  **Handles study endings** (`endStudy` method bundles lots of tasks in one, including appending survey URLs specified in Config.jsm with query strings/sending the user to a survey and uninstalling the add-on).
-
-To use in your study (long-version):
+```sh
+npm install --save shield-studies-addon-utils
+```
 
-* `copyStudyUtils yourAddonSrc/privileged/` which copies `webExtensionApis/study/api.js` and `webExtensionApis/study/schema.json` to your add-on's source directory under `yourAddonSrc/privileged/study`,
+* Run `copyStudyUtils yourAddonSrc/privileged/` which copies `webExtensionApis/study/api.js` and `webExtensionApis/study/schema.json` to your add-on's source directory under `yourAddonSrc/privileged/study`,
 * add the following to your add-on's manifest.json:
 
 ```
@@ -124,47 +56,50 @@ To use in your study (long-version):
   },
 ```
 
-#### Data processing pipelines
+## WebExtension APIs Provided by Shield Studies Add-on Utils
 
-Depending on which data processing pipeline the study add-on is configured to use, the pings end up in different destinations:
+### `browser.study.*`
+
+[`browser.study` API documentation](./webExtensionApis/study/api.md)
+
+#### Supported telemetry pipelines
+
+Depending on which telemetry pipeline is used, the pings end up in different destinations:
 
 * `shield` - The pings end up in the `shield-study` and `shield-study-addon` Telemetry buckets for instant access to submitted payloads via [STMO](https://sql.telemetry.mozilla.org/).
 * `pioneer` - The pings are encrypted and end up in the Pioneer processing pipeline.
-* TBD: `custom-telemetry-events` - The pings end up in the ordinary destination for custom telemetry events (Not Yet Implemented)
+* TODO: `event-telemetry` - The pings end up in the ordinary destination for event telemetry (Not Yet Implemented)
 
 ### `browser.studyDebug.*`
 
 [`browser.studyDebug` API documentation](./webExtensionApis/study/api.md)
 
-Tools for writing tests, getting and resetting StudyUtils internals.
+Used by the project-internal tests only.
 
 ## Engineering your own study add-on
 
-* Check out [mozilla/shield-studies-addon-template/](https://github.com/mozilla/shield-studies-addon-template/) to start from.
+* Check out [the official study add-on example](https://github.com/mozilla/normandy-nextgen-study-example)
 * Read [./docs/engineering.md](./docs/engineering.md) for development documentation aimed at study add-on engineers.
 
-### DO NOT USE These Old Template Repositories
-
-Repositories that should not be used as templates for new studies:
-
-* NO. <https://github.com/benmiroglio/shield-study-embedded-webextension-hello-world-example> - A repository that was created in 2017 to help new Shield/Pioneer engineers to quickly get up and running with a Shield add-on, built upon an older and much more verbose add-on template. It's documentation has been ported to the official template repo.
-* NO. <https://github.com/johngruen/shield-template> - Despite its name, this repo is for static AMO consent pages and does not contain any template for Shield studies
-
 ## Development on the Shield-Studies-Addon-Utils
 
 * Open an issue
 * Hack and file a PR
 * `npm test` must pass.
 * Read [./docs/development-on-the-utils.md](./docs/development-on-the-utils.md) for more in-depth development documentation.
 
-## History of major versions
+## History of recent major versions
 
+* v6.0: Rip out most functionality, keeping only some high priority utils\* that neither the Normandy WebExtension API nor [the Nextgen study example](https://github.com/mozilla/normandy-nextgen-study-example) provides
 * v5.3: [Better study endings](https://github.com/mozilla/shield-studies-addon-utils/issues/246) and `browser.study.fullSurveyUrl()`
 * v5.2: Added Pioneer and Firefox 67 support
 * v5.1: Added preferences for testing overrides, study logger and other enhancements
 * v5: API exposed as a Web Extension Experiment. Minimal viable add-on example added. Test coverage improved. Test utils added.
-* v4.1: Improved utils for common cases
-* v4: First `.jsm` release for shipping studies as [legacy add-ons](https://developer.mozilla.org/Add-ons/Legacy_add_ons). Used packet format for PACKET version 3. (Jetpack / addon-sdk is not at all supported since v4 of this utils library)
-* v3: Attempt to formalize on `shield-study` PACKET version 3. Jetpack based. Prototype used for `raymak/page-reload`. All work abandoned, and no formal npm release in this series. Work done at `v3-shield-packet-format` branch. LAST JETPACK (addon-sdk) RELEASE.
-* v2: Code refactor to es6 `class` with event models. Added cli tooling. Packet format is still arbitrary and per-study. Jetpack based. Last used in studies in Q2 2017.
-* v1: Initial work and thinking. Telemetry packets are rather arbitrary. Jetpack based.
+
+\* Some features that was handled in v5 has not been ported over to neither Normandy nor v6 of the utils:
+
+* expiry
+* lifecycle telemetry (first seen, installed, exit etc)
+* configurable endings (annotated exit telemetry and launching of exit surveys etc)
+* telemetry testing flag specific to study telemetry (disable telemetry via about:config during testing instead)
+* pref-controlled study-specific study logger (use ordinary add-on-scoped logging instead)

bin/copyStudyUtils.js

@@ -9,7 +9,7 @@ const customHelp = `
   # Additional hints
 
   ## cleanup
-  rm -rf <privilegedDirName>/{study,prefs}
+  rm -rf <privilegedDirName>/study
 `;
 
 function correctOutputDir(privilegedDirname) {