DOCS, WIP, FAQ

[gregglind]

What is the current best practices template.

As of 2017-11-16:
http://github.com/mozilla/shield-studies-addon-template

As of 2017-10-03:
http://github.com/gregglind/template-shield-study

Useful LEGACY ADDON building links.

LEGACY ADDON contrasts with "extension" or "addon" which are now webextensions. Legacy Addon is the term for the bootstrap.js with a startup method way of doing things.

• Globals that are defined in bootstrap.js, including __SCRIPT_URI_SPEC__ at https://dxr.mozilla.org/mozilla-central/source/toolkit/mozapps/extensions/internal/XPIProvider.jsm#4335-4353
• https://developer.mozilla.org/en-US/Add-ons/Legacy_add_ons
• https://developer.mozilla.org/en-US/docs/Mozilla/JavaScript_code_modules/XPCOMUtils.jsm#defineLazyModuleGetter()

Explain resource files and chrome.manifest

resource:// maps a FILE SYSTEM list of files, using the ALIASES in a chrome.manifest file.

Example line in chrome.manifest

resource some-addon-name .

and this folder structure

$ tree addon
addon
├── Config.jsm
├── StudyUtils.jsm
├── bootstrap.js
├── chrome.manifest
├── install.rdf
├── lib
│   ├── AddonPrefs.jsm
│   └── Feature.jsm
└── skin
    └── heartbeat-icon.svg

THEN, that chrome.manifest maps these paths between the resource protocol and the jar protocol.

resource://some-addon-name/skin/heartbeat-icon.svg ==> jar:///abs/path/to/theAddon.xpi!/skin/heartbeat-icon.svg

WARNINGS:

1. The characters @ # ; : ? / are not allowed in the alias. This is annoying, because it means you can't use your addonId as the alias
2. Resource files won't show up in dev tools debugger until you attempt to import / use them.
3. If two addons use the same alias, I have no idea of what will happen, but it's PROBABLY BAD. Your alias should be unique to your addon.
4. chrome.manifest resource paths aren't loadable until LEGACY startup. In particular, they are NOT usable during install.

All about LEGACY (Bootstrap / Restartless) addons.

https://developer.mozilla.org/en-US/Add-ons/Bootstrapped_extensions

Is Firefox Wack?

Yes. In particular, LEGACY ADDONS (bootstrap) addons are an orphaned technology, that we still need to use. Debugging is hard. Cu.import is NOT require.

How do I debug?

• about:debugging, does load temporary addon, reload (which won't work if you changed things!) and uninstall.
• tools > web developer > Browser Toolbox (shift alt command i) shows ALL BROWSER LOGGING, which might be where your addon things go. In particular, if you have thrown errors in your bootstrap or other files.
• about:telemetry records all 'current' and 'archive' Telemetry Pings.

when to use isEligible as part of install

From gregglind/57-perception-study#3
I noticed isEligible just returns true -- when would we use this method versus using filter expressions in Normandy?

Reasons

1. JEXL expresssions inadequate. Normandy controls who is offered the study. The JEXL elements it can select on might be inadequate for expressing this criteria.
2. Changes during install. It's a 'backstop' (belt and suspenders) in case the user changes during the download process.
3. If the same study is distributed other ways, beside Normandy.

Writing Tests

Answer: https://seleniumhq.github.io/selenium/docs/api/javascript/module/selenium-webdriver/firefox/index.html

I am having a sadness.

Me too buddy. Me too.

SIGNING

As of 57 (2017-10-05), to get a LEGACY addon to work with BETA or RELEASE, it must be signed with the special legacy signing key, EVEN IF you about:debugging > load temporary addon.

Solutions (in brief)

• use Nightly
• use unbranded Firefox
• get a signed addon.

Initial signing flow

• NAME your addon like this: <addonId>-<version>.xpi
• upload the addon somewhere (such as s3 / Google drive)
• use this bugzilla signing bug template
• get signed addon as an attachement.

See example:

• https://bugzilla.mozilla.org/show_bug.cgi?id=1407757

Tracking and Debugging Telemetry Pings

There is an addon for that! It makes reports.

• https://bugzilla.mozilla.org/attachment.cgi?id=8917534

[biancadanforth]

How do I debug

Perhaps mention that if you use the addon debugger, the only script that logs to the addon debugger console is bootstrap.js. Otherwise you have to look in the browser console, where every script running in the browser dumps logs, warnings and errors. There might be a way to bundle all the modules into a single script file; I guess it'd have to be called bootstrap.js... Something I'd like to look into.

When to use isEligible as part of install

Can you give an example or two of when you've had to use isEligible for each of the three reasons given?

Writing Tests

Marc Robert Wong's share-button-study is the best example of Selenium Webdriver/Geckodriver at work on a bootstrapped addon. Can we point people to this here and say what all he has been able to automate?

[gregglind]

Icons in Legacy Addons

So you want to have 'top level' icon your addon?

# chrome.manifest
content qa-shield-study-helper-icons ./somepath/

install.rdf

    <em:iconURL>chrome://qa-shield-study-helper-icons/content/icon.png</em:iconURL>

NOTE the content in the url, and the chrome as the protocol. These are unexpected.

[biancadanforth]

Feedback from [mostly] Kamyar's and my experience building this shield study:

Template improvements

• Testing the study using npm run firefox should work for all OSes, not just Mac. Perhaps write a script that detects OS and makes necessary changes?
  • Ubuntu: This is trivial to get it to work (just change the FIREFOX_BINARY environment variable in package.json to either /usr/bin/firefox or /usr/bin/firefox-trunk).
  • Windows: I have spent the better part of this morning getting it to work to no avail. Known changes: replace export with set in the firefox command in package.json. Change FIREFOX_BINARY value, but to what? I have tried: C:\\Program Files\\Nightly\\firefox and it fails with ENOENT.
  • Issue made.
• Have a tool (possibly using Firefox GCLI?) to debug/reconfigure/reset study code in real time. @raymak has a lot of ideas about this.

UI capability improvements

• Make it possible to flexibly size UI elements so their dimensions do not have to be hardcoded by OS.
  • For the notification bar and panel/doorhanger element, different OSes display them slightly differently (likely due to system fonts?).
  • Look into the flex attribute for XUL elements.
• Be able to display a custom dropdown menu correctly overlaid over webpage content (rather than shifting down, and preferably using HTML, not XUL) that expands past the original notification bar height.

[biancadanforth]

Draft QA Review Process

This is based on feedback from Gregg's experience reviewing the 57-perception-study.

Shield Team Deliverables to QA:

• A bugzilla bug for the study that can be referenced by QA.
  • With a signed XPI attached for installation of the addon.
• A README.md which describes on a high level what the study is looking at, possibly also listing all the different UI treatments, experimental branches, custom prefs and what they represent.
  • Note: The example README above combines readme, test plan and telemetry documentation into one. We would like to break this out.
• A TESTPLAN.md which describes how to install the addon, what manual tests to perform and how to perform them -- ideally with screenshots/a gif of what it looks like.
  • What QA can test:
    • Install addon
    • Make new profile(s)
    • Set preferences
    • Try locales
    • run Firefox on different platforms (ex: Windows)
    • Check for: security, performance, functional and display issues.
    • If telemetry pings are correct, given they co-install this add-on helper (see TELEMETRY.md below).
• A TELEMETRY.md which describes what telemetry pings are expected and when.

QA Deliverables to Shield team after testing

• A list of issues/tests, flagged by priority (ex: critical blocker or nit), marked as passed or failed.
  • Included in this list is anything QA finds valuable that may not have been part of the list of tests.

[gregglind]

• Link to the wiki for PROCESS stuff, mostly
• get best of "how to shield study"
• get shield-studies-docs for the rest of the best stuff.

consider doing readthedocs?

[gregglind]

https://hacks.mozilla.org/2017/07/introducing-sphinx-js-a-better-way-to-document-large-javascript-projects/

[gregglind]

mozilla/pioneer-utils#4

[biancadanforth]

@motin Did a great job updating the Readme/repo for the template shield study.

We can improve on this by including the npm run firefox command as a semi-automated alternative to manually loading the temporary add-on every time. Ideally the watch command could be integrated into the firefox command, so that when the code changes, not only is a new XPI built, but Firefox is launched in a new profile with various prefs and the addon already loaded.
Consider also making Selenium Webdriver open about:config on starting up Firefox?

[motin]

@biancadanforth

We can improve on this by including the npm run firefox command as a semi-automated alternative to manually loading the temporary add-on every time.

Available https://github.com/gregglind/template-shield-study/pull/15/commits/02c52b5b873117fab6faae6ec9b8a543c1890ae5 as part of https://github.com/gregglind/template-shield-study/pull/15

Ideally the watch command could be integrated into the firefox command

Created a related issue: https://github.com/gregglind/template-shield-study/issues/16

Consider also making Selenium Webdriver open about:config on starting up Firefox?

Greg's latest changes makes about:debugging open on startup. Additionally, the browser console ought to open automatically imo

[gregglind]

QA helper addon

https://bugzilla.mozilla.org/show_bug.cgi?id=1407757

[motin]

Up to date (Oct 24) Telemetry notes from a recent meeting with Georg, the owner of the Telemetry component at Mozilla: https://docs.google.com/document/d/1fzl6bieNkMGQgJUMXl83pDcdBH_ncQuprOsVqN_i2Qo/edit

[motin]

@gregglind Two questions which I am missing answers to from docs:

1. Is it ok to use console.log in the final add-on, or should shield-specific logging be used?
2. Are exceptions caught by shield utils and reported properly, or does each add-on need to catch their exceptions and for instance send an exception-ping with details about the error?

[motin]

@gregglind, update the current best practice template url in the issue description :) mozilla/shield-studies-addon-template#16