<commit_before># Activity Stream (System add-on)

## Contents of this guide

- Installation, set-up, and other basics (this page)
- [Writing unit tests](./unit_testing_guide.md)
- [Adding new Telemetry (user and performance metrics)](./telemetry.md)
- [Reading/changing Firefox prefs](./preferences.md)

## Where to ask questions

- Most of the core dev team can be found on the `#activity-stream` mozilla irc channel.
  You can also direct message the core team (`dmose`, `emtwo`, `jkerim`, `k88hudson`, `Mardak`, `nanj`, `r1cky`, `ursula`, `andreio`)
  or our manager (`tspurway`)
- Our Mozilla slack channel is #activitystream
- File issues/questions on Github: https://github.com/mozilla/activity-stream/issues. We typically triage new issues every Monday.

## How to try Activity Stream

If you just want to try out the current version of Activity Stream in Firefox, you can
install [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly)
go to `about:config`, and set the `browser.newtabpage.activity-stream.enabled` pref
to `true`.

## Source code and submitting pull requests

Inside this repository, there are two versions of Activity Stream; the **test pilot version** (v1)
and the **system add-on version** (v2).

These docs refer to the **system add-on version**, which is the production version
of Activity Stream that is included with Firefox. The latest copy of the source code
for this version can be found in the [system-addon/](../../system-addon/) subdirectory.
You can ignore the other directories/files in the repository.

A copy of this code is exported to Mozilla central on a regular basis, which can
be found at [browser/extensions/activity-stream](https://searchfox.org/mozilla-central/source/browser/extensions/activity-stream).
Keep in mind that some of these files are generated, so if you intend on editing any files, you should
do so in the Github version.

Pull requests should be sent against the master branch of https://github.com/mozilla/activity-stream,
NOT against Mozilla central.

## Prerequisites for development

### Operating system and software

The Activity Stream development environment is designed to work on Mac and Linux.
If you need to develop on Windows, you might want to reach out on IRC (#activity-stream)
if you run into any problems.

You will also need to install:

- Node.js 7+ (On Mac, the best way to install Node.js is to use the [install link on the Node.js homepage](https://nodejs.org/en/))
- npm (packaged with Node.js)

### Activity Stream Github repository

You will need to to clone Activity Stream to a local directory from the `master`
branch of our Github repository: https://github.com/mozilla/activity-stream

```
git clone https://github.com/mozilla/activity-stream.git
```

### Mozilla Central
You will need a local copy of Mozilla Central in a directory named `mozilla-central`. Check the detail of how to get and build Mozilla Central in [Building Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build).
That directory should be a sibling of your local `activity-stream` directory (like so):

```
/
  mozilla-central/
  activity-stream/
```

Check out [these docs on artifact builds](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds)
for instructions about how to download and configure Mozilla Central if you have
never done so before.

## Building

1. Install required dependencies by running `npm install`.
2. To build Activity Stream, run `npm run buildmc` from the root of the
`activity-stream` directory. This will build the js and css files and copy them
into the `browser/extensions/activity-stream` directory inside Mozilla Central.
3. Build and run Firefox from the `mozilla-central` directory by running `./mach build && ./mach run`.

## Continuous development

Running `npm run startmc` will start a process that watches files in `activity-stream`
and continuously builds/copies changes to `mozilla-central`. You will
still need to rebuild Firefox (`./mach build`) if you change `.jsm` files.

## Running unit tests

Run `npm run testmc` to run the unit tests with karma/mocha. The source code for these
tests can be found in `system-addon/test/unit/`.

Our unit tests expect 100% code coverage, so if you see any missing coverage,
you can inspect the coverage report by running `npm run testmc && npm run debugcoverage`.<commit_msg>docs(mc): Add artifact build instructions to the docs. Closes #2779.<commit_after># Activity Stream (System add-on)

## Contents of this guide

- Installation, set-up, and other basics (this page)
- [Writing unit tests](./unit_testing_guide.md)
- [Adding new Telemetry (user and performance metrics)](./telemetry.md)
- [Reading/changing Firefox prefs](./preferences.md)

## Where to ask questions

- Most of the core dev team can be found on the `#activity-stream` mozilla irc channel.
  You can also direct message the core team (`dmose`, `emtwo`, `jkerim`, `k88hudson`, `Mardak`, `nanj`, `r1cky`, `ursula`, `andreio`)
  or our manager (`tspurway`)
- Our Mozilla slack channel is #activitystream
- File issues/questions on Github: https://github.com/mozilla/activity-stream/issues. We typically triage new issues every Monday.

## How to try Activity Stream

If you just want to try out the current version of Activity Stream in Firefox, you can
install [Firefox Nightly](https://www.mozilla.org/en-US/firefox/channel/desktop/#nightly)
go to `about:config`, and set the `browser.newtabpage.activity-stream.enabled` pref
to `true`.

## Source code and submitting pull requests

Inside this repository, there are two versions of Activity Stream; the **test pilot version** (v1)
and the **system add-on version** (v2).

These docs refer to the **system add-on version**, which is the production version
of Activity Stream that is included with Firefox. The latest copy of the source code
for this version can be found in the [system-addon/](../../system-addon/) subdirectory.
You can ignore the other directories/files in the repository.

A copy of this code is exported to Mozilla central on a regular basis, which can
be found at [browser/extensions/activity-stream](https://searchfox.org/mozilla-central/source/browser/extensions/activity-stream).
Keep in mind that some of these files are generated, so if you intend on editing any files, you should
do so in the Github version.

Pull requests should be sent against the master branch of https://github.com/mozilla/activity-stream,
NOT against Mozilla central.

## Prerequisites for development

### Operating system and software

The Activity Stream development environment is designed to work on Mac and Linux.
If you need to develop on Windows, you might want to reach out on IRC (#activity-stream)
if you run into any problems.

You will also need to install:

- Node.js 7+ (On Mac, the best way to install Node.js is to use the [install link on the Node.js homepage](https://nodejs.org/en/))
- npm (packaged with Node.js)

### Activity Stream Github repository

You will need to to clone Activity Stream to a local directory from the `master`
branch of our Github repository: https://github.com/mozilla/activity-stream

```
git clone https://github.com/mozilla/activity-stream.git
```

### Mozilla Central
You will need a local copy of Mozilla Central in a directory named `mozilla-central`. Check the detail of how to get and build Mozilla Central in [Building Firefox](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Simple_Firefox_build).
That directory should be a sibling of your local `activity-stream` directory (like so):

```
/
  mozilla-central/
  activity-stream/
```

Check out [these docs on artifact builds](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Artifact_builds)
for instructions about how to download and configure Mozilla Central if you have
never done so before.

**To build Firefox way faster**, you should definitely enable Artifact builds.
To do that, create a `.mozconfig` (or `mozconfig`) file in the root of your
mozilla-central directory and add the following to it:

```bash
# Automatically download and use compiled C++ components:
ac_add_options --enable-artifact-builds

# Write build artifacts to:
mk_add_options MOZ_OBJDIR=./objdir-frontend
```

## Building

1. Install required dependencies by running `npm install`.
2. To build Activity Stream, run `npm run buildmc` from the root of the
`activity-stream` directory. This will build the js and css files and copy them
into the `browser/extensions/activity-stream` directory inside Mozilla Central.
3. Build and run Firefox from the `mozilla-central` directory by running `./mach build && ./mach run`.

## Continuous development

Running `npm run startmc` will start a process that watches files in `activity-stream`
and continuously builds/copies changes to `mozilla-central`. You will
still need to rebuild Firefox (`./mach build`) if you change `.jsm` files.

## Running unit tests

Run `npm run testmc` to run the unit tests with karma/mocha. The source code for these
tests can be found in `system-addon/test/unit/`.

Our unit tests expect 100% code coverage, so if you see any missing coverage,
you can inspect the coverage report by running `npm run testmc && npm run debugcoverage`.
{'fraction_non_alphanumeric': 0.08964781216648879, 'fraction_numerical': 0.0029882604055496264, 'mean_word_length': 4.515597410241319, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 18, 'lorem ipsum': 0, 'www.': 2, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 7, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '6528147', 'n_tokens_mistral': 2682, 'n_tokens_neox': 2486, 'n_words': 1201}