README.rst
author Felipe Gomes <felipc@gmail.com>
Fri, 14 Apr 2017 19:46:20 -0300
changeset 122 4fad28b4fb92d08d4ec433317afe9374cd0d4478
parent 84 2238294334847ddc14dc28d9db2fc7d11a866018
permissions -rw-r--r--
Bug 1352224 - Follow-up, forgot to add the xpi

This project generates the static files which support Firefox Telemetry
Experiments. This includes the browseable list of current and past
experiments as well as the manifest and .xpi files loaded by Firefox.

Building
========

To build the project, first set up a Python virtualenv:

   virtualenv env

If you do not have ``virtualenv`` in your ``$PATH``, your Python
environment is not complete! Stop now and install virtualenv by
following the instructions at
https://virtualenv.pypa.io/en/latest/virtualenv.html#installation

Activate that virtualenv and ensure our environment is current:

   source env/bin/activate
   python setup.py develop

Finally, build the project by running ``build.py``:

   python build.py destination-path base-url

``destination-path`` is the location of output files. It will be deleted
as part of building.
``base-url`` is the base URL to be used to construct URL references. If
you are testing locally, this should be something like
``http://localhost:8080/``.

The generated directory is meant to be served by Apache. ``AllowOverride``
must be enabled to read the ``.htaccess`` files and it must support
defining ``mod_rewrite`` rules. This, of course, requires ``mod_rewrite``
to be enabled.

For additional info, see
https://wiki.mozilla.org/QA/Desktop_Firefox/Telemetry_Experiments

Creating Experiments
====================

To create a new experiment, create a new directory under ``experiments/``.
This directory **must** have a ``manifest.json`` file describing the behavior
of the experiment. This directory **must** also have one of the following:

* An ``experiment.xpi`` file that is a pre-built XPI/add-on.
* A ``build.py`` file/script that will be executed to produce an XPI.

If both an ``experiment.xpi`` and ``build.py`` file is present, building
will fail.

The per-experiment ``build.py`` script is called with the same Python
interpreter that invokes the main ``build.py``. It will receive a single
argument, the filename of the XPI to generate. If the script exits with a
non-0 exit code or doesn't create the XPI, the main ``build.py`` will
abort.

For more information, refer to the documentation at 
https://wiki.mozilla.org/QA/Telemetry/Developing_a_Telemetry_Experiment

Secrets
=======

Some experiments have secret keys or values that we don't want to check into
source control. There exists a mechanism for defining these.

For experiments needing secret data, their build process will try to load
a secrets file. If the ``EXPERIMENTS_SECRETS`` environment variable is set,
the file defined by that variable will be read. If not set, we will look for
an ``EXPERIMENTS_SECRETS`` file in the ancestors of the experiment's
directory.

The secrets file is a Python file that is evaluated in a sandbox. Variables
set during execution will be exported as secrets.