Skip to content
This repository has been archived by the owner on Feb 29, 2020. It is now read-only.

Commit

Permalink
chore(readme): #3394 Update README to reflect system-addon
Browse files Browse the repository at this point in the history
  • Loading branch information
@k88hudson
k88hudson committed Oct 3, 2017
1 parent bdf3f3a commit 670e25a
Show file tree
Hide file tree
Showing 3 changed files with 63 additions and 164 deletions.
100 changes: 9 additions & 91 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,101 +1,19 @@
# Activity Stream Add-on

[![](https://img.shields.io/badge/available_on-Test_Pilot-0996F8.svg)](https://testpilot.firefox.com/experiments/activity-stream)
[![Coverage Status](https://coveralls.io/repos/github/mozilla/activity-stream/badge.svg?branch=master)](https://coveralls.io/github/mozilla/activity-stream?branch=master)
# Activity Stream

This is the source code for the Activity Stream project, which replaces the "New Tab" of Firefox with a new design based on rich metadata and browsing behavior.

## Installing

To install the release version of the add-on, check out [Test Pilot](https://testpilot.firefox.com/experiments/activity-stream).
We export our code to Mozilla Central on a weekly (or sometimes more frequent) basis.

If you would like to see changes more regularly, you can install the [dev build](https://moz-activity-streams-dev.s3.amazonaws.com/dist/latest.html), which is updated on every commit.
## Where should I file bugs?

## For Localizers

Activity Stream localization is managed via [Pontoon](https://pontoon.mozilla.org/projects/activity-stream-new-tab/), not direct pull requests to the repository. If you want to fix a typo, add a new language, or simply know more about localization, please get in touch with the [existing localization team](https://pontoon.mozilla.org/teams/) for your language, or Mozilla’s [l10n-drivers](https://wiki.mozilla.org/L10n:Mozilla_Team#Mozilla_Corporation) for guidance.
Although we regularly check the ActivityStream:NewTab component on Bugzilla, we generally
like to file bugs at https://github.com/mozilla/activity-stream/issues.

## For Developers

### TLDR; I just want to run it

1. Make sure you have Firefox Beta, node 5.0+ and at npm 3.0+ installed.
2. `npm install`
3. `npm run once`

### Requirements

* You must have at Firefox (45.0+) installed
* node 5.0+, npm 3.0+ (You can install both [here](https://nodejs.org))

### Installation

* install from pre-builts
- [dev](https://s3.amazonaws.com/moz-activity-streams-dev/dist/latest.html)
- [pre-release](https://s3.amazonaws.com/moz-activity-streams-prerelease/dist/latest.html)
- [release](https://moz-activity-streams.s3.amazonaws.com/dist/latest.html)

* install from source

```sh
git clone https://github.com/mozilla/activity-stream.git
cd activity-stream
npm install
npm run package
```

### Configuration

Default configuration is in `config.default.yml`. Create a file called `config.yml` to override any default configuration.

### Running tasks

You may run `npm run help` to see a description of all commands available, which you can run via `npm run [command]`. Here are some important ones:

#### Running the add-on

If you just want to build assets and run the add-on to test it, you may simply run:
If you are interested in contributing, take a look at [this guide](contributing.md) on where to find us and how to contribute,
and [this guide](docs/v2-system-addon/1.GETTING_STARTED.md) for getting your development environment set up.

```sh
npm run once
```

### Developing the add-on

If you want to watch assets and compile them continuously, you will want to run

```sh
npm run start
```

in one terminal session, and

```sh
npm run firefox
```

to start the add-on. This way, when you make changes to the `content-src` folder, they will be reflected immediately without needing to restart the add-on.

### Running Tests

Run `npm test` to run the tests once. Run `npm run help` for more options.

### Running benchmarks

Run `npm run benchmark` to run the benchmarks once. See more details for benchmarking the add-on [here](benchmark_how_to.md).

### Exporting to mozilla-central

To export the bootstrapped add-on to a `mozilla-central` directory that shares the same parent as this current directory, run this command:

```sh
npm run buildmc
```

This will first clear out any existing files from `mozilla-central/browser/extensions/activity-stream` before copying over the newly built files and optionally patching `mozilla-central/browser/extensions/moz.build` to get the add-on built with Firefox. These changes to `mozilla-central` are uncommitted and ready for building/testing/committing.

Note: You can create a `symlink` to the `mozilla-central` repository, e.g.,
## For Localizers

```sh
ln -s ~/other-located-or-named-mozilla-central ../mozilla-central
```
Activity Stream localization is managed via [Pontoon](https://pontoon.mozilla.org/projects/activity-stream-new-tab/), not direct pull requests to the repository. If you want to fix a typo, add a new language, or simply know more about localization, please get in touch with the [existing localization team](https://pontoon.mozilla.org/teams/) for your language, or Mozilla’s [l10n-drivers](https://wiki.mozilla.org/L10n:Mozilla_Team#Mozilla_Corporation) for guidance.
89 changes: 40 additions & 49 deletions contributing.md
View file
Original file line number Diff line number Diff line change
@@ -1,14 +1,19 @@
# Contributing to the Activity Stream Firefox add-on
# Contributing to Activity Stream

Activity Stream is an experiment to enhance the functionality of Firefox's about:newtab page. We welcome new 'streamers' to contribute to the project!
Activity Stream is an enhancement to the functionality of Firefox's about:newtab page. We welcome new 'streamers' to contribute to the project!

- IRC: `#activity-stream` on `irc.mozilla.org`
## Where to ask questions

- Most of the core dev team can be found on the `#activity-stream` channel on `irc.mozilla.org`.
You can also direct message the core team (`dmose`, `emtwo`, `jkerim`, `k88hudson`, `Mardak`, `nanj`, `r1cky`, `ursula`, `andreio`)
or our manager (`tspurway`)
- Slack channel (staff only): #activitystream
- Mailing List: [activity-stream-dev](https://groups.google.com/a/mozilla.com/d/forum/activity-stream-dev)
- File issues/questions on Github: https://github.com/mozilla/activity-stream/issues. We typically triage new issues every Monday.

## Architecture ##

Activity Stream is a Firefox add-on. It uses the Firefox [Add-on SDK](https://developer.mozilla.org/en-US/Add-ons/SDK) and
is written in JavaScript. One of the cool things about Activity Stream is that the
Activity Stream is a Firefox system add-on. One of the cool things about Activity Stream is that the
[content side of the add-on](https://developer.mozilla.org/en-US/Add-ons/SDK/Guides/Content_Scripts)
is written using [ReactJS](https://facebook.github.io/react/). This makes it an awesome project for React hackers to contribute to!

Expand All @@ -21,35 +26,27 @@ a bug, or have a feature idea that you you'd like to see in Activity Stream, fol
- If you can reproduce the bug, give a step-by-step recipe
- Include [stack traces from the console(s)](https://developer.mozilla.org/en-US/docs/Mozilla/Debugging/Debugging_JavaScript) where appropriate
- Screenshots welcome!
- When in doubt, take a look at some [existing issues](https://github.com/mozilla/activity-stream/issues) and emulate

- When in doubt, take a look at some [existing issues](https://github.com/mozilla/activity-stream/issues) and emulate

## Take a Ticket, Hack some Code ##

If you want to write some code, you need to first take a look at the current [Milestone](#milestones-iterations-national-parks-of-canada)
to get an idea what we are currently working on, and to determine the projects [priorities](#priorities-comments). You can then grab a ticket, hack some code,
open up a [Pull Request](#pull-requests), get your code [reviewed](#code-reviews), and see your code merged into
the Activity Stream codebase.

## Milestones, Iterations, National Parks of Canada ##

All work on Activity Stream is broken into two week iterations, which we map into a GitHub [Milestone](https://github.com/mozilla/activity-stream/milestones). At the beginning of the iteration, we prioritize and estimate tickets
into the milestone, attempting to figure out how much progress we can make during the iteration.

## Priorities, Comments ##

All tickets that have been [triaged](#triage) will have a priority tag of either `P1`, `P2`, or `P3`, which are highest to lowest
priorities of tickets in Activity Stream. We love ticket tags and you might also see `Blocked`, `Critical` or `Chemspill` tags, which
indicate our level of anxiety about that particular ticket.

If you are new to the repo, you might want to pay close attention to [`Good first bug`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen+is%3Aissue+label%3A%22Good+first+bug%22),
[`Bug`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen%20is%3Aissue%20label%3ABug%20),
[`Chore`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen+is%3Aissue+label%3AChore) and
[`Bug`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen%20is%3Aissue%20label%3ABug%20),
[`Chore`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen+is%3Aissue+label%3AChore) and
[`Polish`](https://github.com/mozilla/activity-stream/issues?q=is%3Aopen+is%3Aissue+label%3APolish) tags, as these are
typically a great way to get started. You might see a bug that is not yet assigned to anyone, or start a conversation with
an engineer in the ticket itself, expressing your interest in taking the bug. If you take the bug, someone will set
the ticket to [`Assigned to Contributor`](https://github.com/mozilla/activity-stream/issues?utf8=%E2%9C%93&q=is%3Aopen%20is%3Aissue%20label%3A%22Assigned%20to%20contributor%22%20), which is a way we can be pro-active about helping you succeed in fixing the bug.

When you have some code written, you can open up a [Pull Request](#pull-requests), get your code [reviewed](#code-reviews), and see your code merged into the Activity Stream codebase.

If you are thinking about contributing on a longer-term basis, check out the section on [milestones](#milestones) and [priorities](#priorities)
to get a sense of how we plan and prioritize work.

## Setting up your development environment

Check out [this guide](docs/v2-system-addon/1.GETTING_STARTED.md) on how to install dependencies, get set up, and run tests.

## Pull Requests ##

You have identified the bug, written code and now want to get it into the main repo using a [Pull Request](https://help.github.com/articles/about-pull-requests/).
Expand All @@ -72,35 +69,13 @@ module owners will be along and will either:
Typically, you will iterate on the PR, making changes and pushing your changes to new commits on the PR. When the reviewer is
satisfied that your code is good-to-go, you will get the coveted `R+` comment, and your code can be merged. If you have
commit permission, you can go ahead and merge the code to `master`, otherwise, it will be done for you.

Our project prides itself on it's respectful, patient and positive attitude when it comes to reviewing contributor's code, and as such,
we expect contributors to be respectful, patient and positive in their communications as well. Let's be friends and learn
from each other for a free and awesome web!

[Mozilla Committing Rules and Responsibilities](https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Committing_Rules_and_Responsibilities)

## Unit Tests ##

We have a [detailed write-up](https://github.com/mozilla/activity-stream/blob/master/content-test/addon-tests-how-to.md) on
Activity Stream unit testing. This is an important read, as there are **significant** JavaScript differences when
writing Firefox add-on code that must be taken into consideration.

Our build process will run unit tests and code coverage tools automatically. Make sure to put your tests in
`content-test` directory, that all tests pass, and that you are
not responsible for unduly decreasing the overall code coverage percentage.

To run tests from the command line:

`npm run test`


## Triage ##

The project team meets weekly (in a closed meeting, for the time being), to discuss project priorities, to triage new tickets, and to
redistribute the work amongst team members. Any contributors tickets or PRs are carefully considered, prioritized, and if needed,
assigned a reviewer. The project's GitHub [Milestone page](https://github.com/mozilla/activity-stream/milestones) is the best
place to look for up-to-date information on project priorities and current workload.

## Git Commit Guidelines ##

We loosely follow the [Angular commit guidelines](https://github.com/angular/angular.js/blob/master/CONTRIBUTING.md#type) of `<type>(<scope>): <subject>` where `type` must be one of:
Expand Down Expand Up @@ -140,8 +115,24 @@ It should include the motivation for the change and contrast this with previous
The footer should contain any information about **Breaking Changes** and is also the place to
reference GitHub issues that this commit **Closes**.

## Milestones ##

All work on Activity Stream is broken into two week iterations, which we map into a GitHub [Milestone](https://github.com/mozilla/activity-stream/milestones). At the beginning of the iteration, we prioritize and estimate tickets
into the milestone, attempting to figure out how much progress we can make during the iteration.

## Priorities ##

All tickets that have been [triaged](#triage) will have a priority tag of either `P1`, `P2`, `P3`, or `P4` which are highest to lowest
priorities of tickets in Activity Stream. We love ticket tags and you might also see `Blocked`, `Critical` or `Chemspill` tags, which
indicate our level of anxiety about that particular ticket.

## Triage ##

The project team meets weekly (in a closed meeting, for the time being), to discuss project priorities, to triage new tickets, and to
redistribute the work amongst team members. Any contributors tickets or PRs are carefully considered, prioritized, and if needed,
assigned a reviewer. The project's GitHub [Milestone page](https://github.com/mozilla/activity-stream/milestones) is the best
place to look for up-to-date information on project priorities and current workload.

## License

MPL 2.0

38 changes: 14 additions & 24 deletions docs/v2-system-addon/1.GETTING_STARTED.md
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
# Activity Stream (System add-on)
# Activity Stream Development Guide

## Contents of this guide

Expand All @@ -8,33 +8,17 @@
- [Reading/changing Firefox prefs](./preferences.md)
- [Adding new sections](./sections.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`.
or any version of Firefox >= 57.0. If you still don't see activity stream, go to `about:config`,
and make sure the `browser.newtabpage.activity-stream.enabled` pref is set 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).
A copy of the code in the [system-addon/](../../system-addon/) subdirectory of this repository
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.

Expand Down Expand Up @@ -103,10 +87,16 @@ Running `npm run startmc` will start a process that watches files in `activity-s
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
## 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`.
We have a [detailed write-up](unit_testing_guide.md) on
Activity Stream unit testing. This is an important read, as there are **significant** JavaScript differences when
writing Firefox add-on code that must be taken into consideration.

Our build process will run unit tests and code coverage tools automatically. Make that all tests pass,
and that you are not responsible for unduly decreasing the overall code coverage percentage.

If you see any missing test coverage, you can inspect the coverage report by running `npm run testmc && npm run debugcoverage`.

0 comments on commit 670e25a

Please sign in to comment.