Loop/Development
Contents
Bug Tracking and Repositories
Need Help, want to discuss with Loop developers?
If you need help or want to discuss something with the Loop developers, then visit us on #loop on irc.mozilla.org - if you need more information about IRC, see our IRC page.
Tracking
Bugs are stored in bugzilla:
- Desktop & Standalone (aka 'link generator' and 'link clicker', respectively): 'Loop' product, 'Client' component
- Server: 'Loop' product, 'Server' component
Looking for bugs?
Try one of the good first bugs (simple bugs that are easy to fix) or a good next bug.
There's also mentored bugs where are developers have signed up to help you fix the bugs. Most of these will be in the good first and next bug groups above.
Or if not, take a look at our ranked priority list and choose one from there.
Repositories
Loop is contained across two repositories:
- Master repository for Desktop and Standalone UI: Loop add-on and web frontend
- Loop server
Directories
All files, apart from desktop locales are in mozilla-central, under browser/components/loop/
. Within that directory there is:
- *.jsm - Various modules used within Firefox desktop
- build-jsx used to build the required jsx files
- content/ - These files are all used on the desktop for the Loop panel and conversation window. They are loaded into content space rather than chrome
- content/shared - Used for Firefox desktop, but also used for the standalone UI
- standalone/ - Files used by the standalone application, including commands to make and run a standalone server (see below)
- standalone/content - The content files for the standalone application
- ui/ - A UI showcase, used to aid development and layout of styles for the various parts of the UI
A small bit of integration code with Firefox can be found in browser-loop.js.
Loop Software Architecture
More details on the structure coming soon. We have parts of Loop that run in a web-content space (those typically below a content
directory), and other parts that work in a gecko privileged space (these are typically in the root directory of browser/components/loop
).
A lot of the content files use a Flux based architecture, read more about that here.
Getting started with Firefox Desktop and Standalone development
Warning: most of these instructions are out of date, for correct information please see the loop repository and the Contributing file
Additional Requirements
For Loop development, there's currently a couple of extra requirements on top of the Firefox desktop build requirements.
These are NodeJS (note, though, that you MUST currently use an old version, 0.10), react-tools and eslint.
Note that when building Firefox itself, be sure to setac_add_options --enable-optimizein your mozconfig to avoid problems with automated tests timing out.
Install NodeJS 0.10 first, then follow the instructions below
Mac installation of node 0.10
brew install homebrew/versions/node010
Windows Specific
There's a little bit more set-up required specific to Windows.
- Start up the mozilla-build shell via one of the start-shell-msvc*.bat files
- Work out your APPDATA path:
echo $APPDATA
- In your APPDATA, you'll need to replace various parts, so:
c:\Users\moztest\AppData\Roaming
becomes:
/c/Users/moztest/AppData/Roaming
- Now setup your profile file, replace the
<path to APPDATA>
with the path you just worked out.
echo PATH=$PATH:/c/Program\ Files/nodejs:<path to APPDATA>/npm >> ~/.profile
- Now exit your shell/console and re-enter it.
- Complete the steps in the "All Platforms" section
If you need to change the path later, you can edit the ~/.profile file.
All Platforms
Once you have Node installed, use npm (which comes with it) to globally install the extra required items:
npm install -g react-tools@0.12.2 npm install -g eslint npm install -g eslint-plugin-react
Standalone server - Link-clicker UI and unit test development
We have a server that helps running the unit tests manually, there's also the ui-showcase which helps with previewing layouts before starting Firefox.
cd browser/components/loop/standalone make install make runserver
You only need to do make runserver
on subsequent runs. Although make install
may be required occasionally if dependencies get updated.
Visiting test pages
To view the unit tests visit:
http://localhost:3000/test/
To view the UI-showcase, visit:
http://localhost:3000/ui/
Testing out changes to the standalone UI
The standalone part of Loop (also known as the link-clicker UI) can be viewed in any web browser, and is hosted on a server. You can hook the development server up to talk to one of the servers to be able to test changes to the standalone UI.
To do this, setup the standalone server as described above, then rather than a simple make runserver
, do:
LOOP_SERVER_URL=https://path/to/server make runserver
Replace the server path with one of:
- Development server: https://loop-dev.stage.mozaws.net
- Production server: https://loop.services.mozilla.com
(Generally its better to use the development server than the production one to avoid affecting the stats of production usage).
For the desktop side (also known as the link-generator):
- You may wish to create a new profile for testing purposes (since changing the pref below will loose your previously created conversations), e.g:
/path/to/firefox -createProfile myTestProfile ./mach run -P myTestProfile -purgecaches
- Visit about:config, change the
loop.server
preference to behttps://loop-dev.stage.mozaws.net/v0
- Restart Firefox after changing the pref
- From the Hello panel, select "Start a conversation"
- Copy the url, and paste it into a browser window, but change the url
You should now be able to join the room with that instance.
Developing
If you're altering any of the javascript files, you need to make sure you alter the jsx versions if they exist.
You can start up the jsx compiler so that it watches the files and continuously updates them whilst the jsx is left running:
cd browser/components/loop ./build-jsx -w
To stop watching files and quit jsx, just use ctrl-c
Note: Note: On windows, build-jsx doesn't currently do the version check for the react version, so please keep an eye on the suggested version in case it is updated.
Linting
We use eslint to parse the Loop files and check them for correctness before landing.
See the README.txt for how to run it.
UI-showcase
If you've got the standalone server running, you can view this by visiting http://localhost:3000/ui/ . This lets you layout the content pages (the parts displayed in the panel and conversation view) in a web context before loading and testing them in Firefox itself.
This can save you a considerable amount of time, because you don't have to (re-)build each time you made a change to see what effect it had.
Running Tests
There's a file located at browser/components/loop/run-all-loop-tests.sh
which allows all loop related tests to be run at the same time.
For information on running the tests individually, see the README.txt
file.
Creating Patches
Creating patches happens in exactly the same manner as for the rest of Firefox. See our documentation on the Mozilla Developer Network for how to create and submit a patch.