зеркало из https://github.com/mozilla/treeherder.git
Bug 1522101 - Use Prettier to format Markdown
This commit is contained in:
Ed Morley
Родитель
96fb922072
Коммит
2d787000bd
|
|
@ -10,4 +10,3 @@ ui/partials/
|
|||
# Ignore Prettier-supported filetypes that we haven't yet converted to its style,
|
||||
# so that "format on save" doesn't try to format them when making unrelated changes.
|
||||
*.json
|
||||
*.md
|
||||
|
|
|
|||
11
README.md
11
README.md
|
|
@ -1,5 +1,5 @@
|
|||
treeherder
|
||||
==================
|
||||
# treeherder
|
||||
|
||||
[](https://whatsdeployed.io/s-dqv)
|
||||
[](https://travis-ci.org/mozilla/treeherder)
|
||||
[](https://pyup.io/repos/github/mozilla/treeherder/)
|
||||
|
|
@ -7,21 +7,20 @@ treeherder
|
|||
[](https://david-dm.org/mozilla/treeherder?type=dev)
|
||||
[](https://treeherder.readthedocs.io/?badge=latest)
|
||||
|
||||
|
||||
#### Description
|
||||
|
||||
[Treeherder](https://treeherder.mozilla.org) is a reporting dashboard for Mozilla checkins. It allows users to see the results of automatic builds and their respective tests. The Treeherder service manages the etl layer for data ingestion, web services, and the data model behind Treeherder.
|
||||
|
||||
|
||||
#### Instances
|
||||
|
||||
Treeherder exists on two instances, [stage](https://treeherder.allizom.org) for pre-deployment validation, and [production](https://treeherder.mozilla.org) for actual use.
|
||||
|
||||
|
||||
#### Installation
|
||||
|
||||
The steps to run Treeherder are provided [here](https://treeherder.readthedocs.io/installation.html).
|
||||
|
||||
The steps to run only the UI are provided [here](https://treeherder.readthedocs.io/installation.html#ui-development).
|
||||
|
||||
|
||||
#### Links
|
||||
|
||||
Visit our project tracking Wiki at:
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
Administrating Treeherder
|
||||
=========================
|
||||
# Administrating Treeherder
|
||||
|
||||
Direct database access
|
||||
----------------------
|
||||
## Direct database access
|
||||
|
||||
For cases where the REST API just isn't enough, a 3rd-party
|
||||
application might want to connect directly to the Treeherder
|
||||
|
|
|
|||
|
|
@ -1,8 +1,6 @@
|
|||
Backend tasks
|
||||
==========================
|
||||
# Backend tasks
|
||||
|
||||
Running the tests
|
||||
-----------------
|
||||
## Running the tests
|
||||
|
||||
You can run flake8, isort and the pytest suite inside the Vagrant VM, using:
|
||||
|
||||
|
|
@ -14,7 +12,7 @@ Note: The Selenium tests will be skipped unless `yarn build` has been manually r
|
|||
|
||||
Or for more control, run each tool individually:
|
||||
|
||||
* [pytest](https://docs.pytest.org/en/stable/):
|
||||
- [pytest](https://docs.pytest.org/en/stable/):
|
||||
|
||||
```bash
|
||||
vagrant ~/treeherder$ pytest tests/
|
||||
|
|
@ -38,15 +36,15 @@ Or for more control, run each tool individually:
|
|||
vagrant ~/treeherder$ pytest tests/selenium/ --html report.html
|
||||
```
|
||||
|
||||
* [flake8](https://flake8.readthedocs.io/):
|
||||
- [flake8](https://flake8.readthedocs.io/):
|
||||
|
||||
```bash
|
||||
vagrant ~/treeherder$ flake8
|
||||
```
|
||||
|
||||
NB: If running flake8 from outside of the VM, ensure you are using the same version as used on Travis (see ``requirements/dev.txt``).
|
||||
NB: If running flake8 from outside of the VM, ensure you are using the same version as used on Travis (see `requirements/dev.txt`).
|
||||
|
||||
* [isort](https://github.com/timothycrosley/isort) (checks the [Python import style](code_style.html#python-imports)):
|
||||
- [isort](https://github.com/timothycrosley/isort) (checks the [Python import style](code_style.html#python-imports)):
|
||||
|
||||
To run interactively:
|
||||
|
||||
|
|
@ -62,15 +60,13 @@ Or for more control, run each tool individually:
|
|||
|
||||
NB: isort must be run from inside the VM, since a populated (and up to date) virtualenv is required so that isort can correctly categorise the imports.
|
||||
|
||||
Hide Jobs with Tiers
|
||||
--------------------
|
||||
## Hide Jobs with Tiers
|
||||
|
||||
To hide jobs we use the job's ``tier`` setting. Jobs with ``tier`` of 3 are
|
||||
hidden by default. For TaskCluster, edit the task definition to include the
|
||||
``tier`` setting in the Treeherder section.
|
||||
To hide jobs we use the job's `tier` setting. Jobs with `tier` of 3 are
|
||||
hidden by default. For TaskCluster, edit the task definition to include the
|
||||
`tier` setting in the Treeherder section.
|
||||
|
||||
Connecting to Services Running inside Vagrant
|
||||
---------------------------------------------
|
||||
## Connecting to Services Running inside Vagrant
|
||||
|
||||
Treeherder uses various services to function, eg MySQL, Elasticsearch, etc.
|
||||
At times it can be useful to connect to them from outside the Vagrant VM.
|
||||
|
|
@ -80,10 +76,9 @@ These allow one to connect to services running inside a Vagrant VM.
|
|||
|
||||
In the below example we're mapping VM port 3306 (MySQL's default port) to host port 3308.
|
||||
|
||||
```ruby
|
||||
config.vm.network "forwarded_port", guest: 3306, host: 3308, host_ip: "127.0.0.1"
|
||||
```
|
||||
|
||||
```ruby
|
||||
config.vm.network "forwarded_port", guest: 3306, host: 3308, host_ip: "127.0.0.1"
|
||||
```
|
||||
|
||||
```eval_rst
|
||||
.. note::
|
||||
|
|
@ -93,27 +88,24 @@ In the below example we're mapping VM port 3306 (MySQL's default port) to host p
|
|||
|
||||
With MySQL exposed at port 3308 you can connect to it from your host OS with the following credentials:
|
||||
|
||||
* host: `localhost`
|
||||
* port: `3308`
|
||||
* user: `root`
|
||||
* password: leave blank
|
||||
|
||||
- host: `localhost`
|
||||
- port: `3308`
|
||||
- user: `root`
|
||||
- password: leave blank
|
||||
|
||||
Other services running inside the VM, such as Elasticsearch, can be accessed in the same way.
|
||||
|
||||
|
||||
[client Git log]: https://github.com/mozilla/treeherder/commits/master/treeherder/client
|
||||
[client git log]: https://github.com/mozilla/treeherder/commits/master/treeherder/client
|
||||
[client.py]: https://github.com/mozilla/treeherder/blob/master/treeherder/client/thclient/client.py
|
||||
[bug 1236965]: https://bugzilla.mozilla.org/show_bug.cgi?id=1236965
|
||||
|
||||
Releasing a new version of the Python client
|
||||
--------------------------------------------
|
||||
## Releasing a new version of the Python client
|
||||
|
||||
* Determine whether the patch, minor or major version should be bumped, by
|
||||
- Determine whether the patch, minor or major version should be bumped, by
|
||||
inspecting the [client Git log].
|
||||
* File a separate bug for the version bump.
|
||||
* Open a PR to update the version listed in [client.py].
|
||||
* Use Twine to publish **both** the sdist and the wheel to PyPI, by running
|
||||
- File a separate bug for the version bump.
|
||||
- Open a PR to update the version listed in [client.py].
|
||||
- Use Twine to publish **both** the sdist and the wheel to PyPI, by running
|
||||
the following from the root of the Treeherder repository:
|
||||
|
||||
```bash
|
||||
|
|
@ -124,6 +116,6 @@ Releasing a new version of the Python client
|
|||
> twine upload dist/*
|
||||
```
|
||||
|
||||
* File a ``Release Engineering::Buildduty`` bug requesting that the sdist
|
||||
- File a `Release Engineering::Buildduty` bug requesting that the sdist
|
||||
and wheel releases (plus any new dependent packages) be added to the
|
||||
internal PyPI mirror. For an example, see [bug 1236965].
|
||||
internal PyPI mirror. For an example, see [bug 1236965].
|
||||
|
|
|
|||
|
|
@ -1,23 +1,21 @@
|
|||
Code Style
|
||||
==========
|
||||
# Code Style
|
||||
|
||||
Python imports
|
||||
--------------
|
||||
## Python imports
|
||||
|
||||
[isort](https://github.com/timothycrosley/isort) enforces the following Python global import order:
|
||||
|
||||
* ``from __future__ import ...``
|
||||
* Python standard library
|
||||
* Third party modules
|
||||
* Local project imports (absolutely specified)
|
||||
* Local project imports (relative path, eg: ``from .models import Credentials``)
|
||||
- `from __future__ import ...`
|
||||
- Python standard library
|
||||
- Third party modules
|
||||
- Local project imports (absolutely specified)
|
||||
- Local project imports (relative path, eg: `from .models import Credentials`)
|
||||
|
||||
In addition:
|
||||
|
||||
* Each group should be separated by a blank line.
|
||||
* Within each group, all ``import ...`` statements should be before ``from ... import ...``.
|
||||
* After that, sort alphabetically by module name.
|
||||
* When importing multiple items from one module, use this style:
|
||||
- Each group should be separated by a blank line.
|
||||
- Within each group, all `import ...` statements should be before `from ... import ...`.
|
||||
- After that, sort alphabetically by module name.
|
||||
- When importing multiple items from one module, use this style:
|
||||
|
||||
```python
|
||||
from django.db import (models,
|
||||
|
|
@ -31,8 +29,7 @@ Note: It's not possible to disable isort wrapping style checking, so for now we'
|
|||
most deterministic [wrapping mode](https://github.com/timothycrosley/isort#multi-line-output-modes)
|
||||
to reduce the line length guess-work when adding imports, even though it's not the most concise.
|
||||
|
||||
UI
|
||||
--
|
||||
## UI
|
||||
|
||||
We use Prettier for JS/JSX formatting and the [Airbnb](https://github.com/airbnb/javascript)
|
||||
guide for non-style related best practices. Both are validated using ESlint (see Validating
|
||||
|
|
@ -48,10 +45,11 @@ However we recommend that you instead
|
|||
and enable "format on save" for the most seamless development workflow.
|
||||
|
||||
Imports in JS/JSX must be ordered like so (with newlines between each group):
|
||||
|
||||
1. external modules (eg `'react'`)
|
||||
2. modules from a parent directory (eg `'../foo'`)
|
||||
3. "sibling" modules from the same or a sibling's directory (eg `'./bar'` or './bar/baz')
|
||||
|
||||
For CSS, we use [reactstrap](https://reactstrap.github.io/) and Bootstrap's utility classes as
|
||||
much as possible before adding custom CSS to a style sheet. Any custom style that can be made
|
||||
reusable should be named generically and stored in the ``ui/css/treeherder-global.css`` file.
|
||||
reusable should be named generically and stored in the `ui/css/treeherder-global.css` file.
|
||||
|
|
|
|||
|
|
@ -1,45 +1,40 @@
|
|||
Common tasks
|
||||
============
|
||||
# Common tasks
|
||||
|
||||
Building the docs locally
|
||||
-------------------------
|
||||
## Building the docs locally
|
||||
|
||||
* Either ``vagrant ssh`` into the VM, or else activate a virtualenv on the host machine.
|
||||
* From the root of the Treeherder repo, run:
|
||||
- Either `vagrant ssh` into the VM, or else activate a virtualenv on the host machine.
|
||||
- From the root of the Treeherder repo, run:
|
||||
|
||||
```bash
|
||||
> pip install -r requirements/docs.txt
|
||||
> make livehtml
|
||||
```
|
||||
|
||||
* Visit <http://127.0.0.1:8001> to view the docs.
|
||||
* Source changes will result in automatic rebuilds and browser page reload.
|
||||
- Visit <http://127.0.0.1:8001> to view the docs.
|
||||
- Source changes will result in automatic rebuilds and browser page reload.
|
||||
|
||||
Updating package.json
|
||||
---------------------
|
||||
## Updating package.json
|
||||
|
||||
* Always use ``yarn`` to make changes, not ``npm``, so that ``yarn.lock`` remains in sync.
|
||||
* Add new packages using ``yarn add <PACKAGE>`` (``yarn.lock`` will be automatically updated).
|
||||
* After changes to ``package.json`` use ``yarn install`` to install them and automatically update ``yarn.lock``.
|
||||
* For more details see the [Yarn documentation].
|
||||
- Always use `yarn` to make changes, not `npm`, so that `yarn.lock` remains in sync.
|
||||
- Add new packages using `yarn add <PACKAGE>` (`yarn.lock` will be automatically updated).
|
||||
- After changes to `package.json` use `yarn install` to install them and automatically update `yarn.lock`.
|
||||
- For more details see the [Yarn documentation].
|
||||
|
||||
[Yarn documentation]: https://yarnpkg.com/en/docs/usage
|
||||
[yarn documentation]: https://yarnpkg.com/en/docs/usage
|
||||
|
||||
Add a new Mercurial repository
|
||||
------------------------------
|
||||
## Add a new Mercurial repository
|
||||
|
||||
To add a new repository, the following steps are needed:
|
||||
|
||||
* Append new repository information to the fixtures file located at:
|
||||
- Append new repository information to the fixtures file located at:
|
||||
`treeherder/model/fixtures/repository.json`
|
||||
* Load the file you edited with the loaddata command:
|
||||
- Load the file you edited with the loaddata command:
|
||||
|
||||
```bash
|
||||
vagrant ~/treeherder$ ./manage.py loaddata repository
|
||||
```
|
||||
|
||||
* Restart any running gunicorn/celery processes.
|
||||
- Restart any running gunicorn/celery processes.
|
||||
|
||||
For more information on adding a new GitHub repository, see
|
||||
[Adding a GitHub repository](submitting_data.html#adding-a-github-repository).
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
Schema Validation
|
||||
=================
|
||||
# Schema Validation
|
||||
|
||||
Some data types in Treeherder will have JSON Schema files in the form of YAML.
|
||||
You can use these files to validate your data prior to submission to be sure
|
||||
|
|
@ -7,7 +6,7 @@ it is in the right format.
|
|||
|
||||
You can find all our data schemas in the [schemas] folder.
|
||||
|
||||
To validate your file against a ``yml`` file, you can use something like the
|
||||
To validate your file against a `yml` file, you can use something like the
|
||||
following example code:
|
||||
|
||||
```python
|
||||
|
|
@ -18,7 +17,7 @@ schema = yaml.load(open("schemas/text-log-summary-artifact.yml"))
|
|||
jsonschema.validate(data, schema)
|
||||
```
|
||||
|
||||
This will give output telling you if your ``data`` element passes validation,
|
||||
This will give output telling you if your `data` element passes validation,
|
||||
and, if not, exactly where it is out of compliance.
|
||||
|
||||
[schemas]: https://github.com/mozilla/treeherder/tree/master/schemas
|
||||
|
|
|
|||
|
|
@ -1,30 +1,26 @@
|
|||
Installation
|
||||
============
|
||||
# Installation
|
||||
|
||||
Prerequisites
|
||||
-------------
|
||||
## Prerequisites
|
||||
|
||||
* If you are new to Mozilla or the A-Team, read the [A-Team Bootcamp].
|
||||
* Install [Git]
|
||||
* Clone the [treeherder repo] from GitHub.
|
||||
- If you are new to Mozilla or the A-Team, read the [A-Team Bootcamp].
|
||||
- Install [Git]
|
||||
- Clone the [treeherder repo] from GitHub.
|
||||
|
||||
If you only want to hack on the frontend, see the UI Development section below. If you want to hack on the backend or work full-stack, see the [Server and Full-stack Development](#server-and-full-stack-development) section.
|
||||
|
||||
UI Development
|
||||
==============
|
||||
# UI Development
|
||||
|
||||
To get started:
|
||||
|
||||
* Install [Node.js] and [Yarn] (see [package.json] for known compatible versions, listed under `engines`).
|
||||
* Run ``yarn install`` to install all dependencies.
|
||||
- Install [Node.js] and [Yarn] (see [package.json] for known compatible versions, listed under `engines`).
|
||||
- Run `yarn install` to install all dependencies.
|
||||
|
||||
Running the standalone development server
|
||||
-----------------------------------------
|
||||
## Running the standalone development server
|
||||
|
||||
The default development server runs the unminified UI and fetches data from the
|
||||
production site. You do not need to set up the Vagrant VM unless making backend changes.
|
||||
|
||||
* Start the development server by running:
|
||||
|
||||
- Start the development server by running:
|
||||
|
||||
```bash
|
||||
$ yarn start
|
||||
|
|
@ -36,7 +32,7 @@ production site. You do not need to set up the Vagrant VM unless making backend
|
|||
Any action you take, such as classifying a job, will affect the live production front-end of Treeherder so we recommend developing against `stage` (details below) unless there's something data-specific that must be addressed on production.
|
||||
```
|
||||
|
||||
* The server will perform an initial build and then watch for new changes. Once the server is running, you can navigate to: <http://localhost:5000> to see the UI.
|
||||
- The server will perform an initial build and then watch for new changes. Once the server is running, you can navigate to: <http://localhost:5000> to see the UI.
|
||||
|
||||
To run the unminified UI with data from the staging site instead of the production site, type:
|
||||
|
||||
|
|
@ -50,10 +46,9 @@ production site. You do not need to set up the Vagrant VM unless making backend
|
|||
$ BACKEND=<url> yarn start
|
||||
```
|
||||
|
||||
This will run the unminified UI using ``<url>`` as the service domain.
|
||||
This will run the unminified UI using `<url>` as the service domain.
|
||||
|
||||
Validating JavaScript
|
||||
---------------------
|
||||
## Validating JavaScript
|
||||
|
||||
We run our JavaScript code in the frontend through [ESLint] to ensure
|
||||
that new code has a consistent style and doesn't suffer from common
|
||||
|
|
@ -75,16 +70,15 @@ $ yarn lint --fix
|
|||
|
||||
See the [code style](code_style.html#ui) section for more details.
|
||||
|
||||
Running the unit tests
|
||||
----------------------
|
||||
## Running the unit tests
|
||||
|
||||
Currently, most of the unit tests for the UI are run with [Karma] and [Jasmine]. However, we are
|
||||
migrating from [Karma] to [Jest]. So new tests should be written in [Jest]. React components are tested with [enzyme].
|
||||
migrating from [Karma] to [Jest]. So new tests should be written in [Jest]. React components are tested with [enzyme].
|
||||
|
||||
To run the tests:
|
||||
|
||||
* If you haven't already done so, install local dependencies by running ``yarn install`` from the project root.
|
||||
* Then run ``yarn test`` to execute the tests (both Karma and Jest tests will be run).
|
||||
- If you haven't already done so, install local dependencies by running `yarn install` from the project root.
|
||||
- Then run `yarn test` to execute the tests (both Karma and Jest tests will be run).
|
||||
|
||||
While working on the frontend, you may wish to watch JavaScript files and re-run tests
|
||||
automatically when files change. To do this, you may run one of the following commands:
|
||||
|
|
@ -101,19 +95,16 @@ $ yarn jest:watch
|
|||
|
||||
The tests will perform an initial run and then re-execute each time a project file is changed.
|
||||
|
||||
|
||||
Server and Full-stack Development
|
||||
=================================
|
||||
# Server and Full-stack Development
|
||||
|
||||
To get started:
|
||||
|
||||
* Install [Virtualbox] and [Vagrant] (latest versions recommended).
|
||||
* Linux only: An nfsd server is required. You can install this on Ubuntu by running `apt-get install nfs-common nfs-kernel-server`
|
||||
- Install [Virtualbox] and [Vagrant] (latest versions recommended).
|
||||
- Linux only: An nfsd server is required. You can install this on Ubuntu by running `apt-get install nfs-common nfs-kernel-server`
|
||||
|
||||
Setting up Vagrant
|
||||
------------------
|
||||
## Setting up Vagrant
|
||||
|
||||
* Open a shell, cd into the root of the Treeherder repository, and type:
|
||||
- Open a shell, cd into the root of the Treeherder repository, and type:
|
||||
|
||||
```bash
|
||||
> vagrant up --provision
|
||||
|
|
@ -123,13 +114,13 @@ Setting up Vagrant
|
|||
complete, depending on your network performance. If you experience
|
||||
any errors, see the [troubleshooting page](troubleshooting.md).
|
||||
|
||||
It is *very important* that the provisioning process complete successfully before
|
||||
It is _very important_ that the provisioning process complete successfully before
|
||||
trying to interact with your test instance of treeherder: some things might
|
||||
superficially seem to work a partially configured machine, but
|
||||
it is almost guaranteed that some things *will break* in
|
||||
it is almost guaranteed that some things _will break_ in
|
||||
hard-to-diagnose ways if vagrant provision is not run to completion.
|
||||
|
||||
* Once the virtual machine is set up, connect to it using:
|
||||
- Once the virtual machine is set up, connect to it using:
|
||||
|
||||
```bash
|
||||
> vagrant ssh
|
||||
|
|
@ -137,16 +128,15 @@ Setting up Vagrant
|
|||
|
||||
A python virtual environment will be activated on login, and the working directory will be the treeherder source directory shared from the host machine.
|
||||
|
||||
* For the full list of available Vagrant commands (for example, suspending the VM when you are finished for the day),
|
||||
- For the full list of available Vagrant commands (for example, suspending the VM when you are finished for the day),
|
||||
see their [command line documentation](https://www.vagrantup.com/docs/cli/).
|
||||
|
||||
* If you just wish to [run the tests](common_tasks.html#running-the-tests),
|
||||
- If you just wish to [run the tests](common_tasks.html#running-the-tests),
|
||||
you can stop now without performing the remaining steps.
|
||||
|
||||
Starting a local Treeherder instance
|
||||
------------------------------------
|
||||
## Starting a local Treeherder instance
|
||||
|
||||
* Start a gunicorn instance inside the Vagrant VM, to serve the static UI and API requests:
|
||||
- Start a gunicorn instance inside the Vagrant VM, to serve the static UI and API requests:
|
||||
|
||||
```bash
|
||||
vagrant ~/treeherder$ ./bin/run_gunicorn
|
||||
|
|
@ -160,7 +150,7 @@ Starting a local Treeherder instance
|
|||
|
||||
this is more convenient because it automatically refreshes every time there's a change in the code.
|
||||
|
||||
* You must also start the UI dev server. Open a new terminal window and ``vagrant ssh`` to
|
||||
- You must also start the UI dev server. Open a new terminal window and `vagrant ssh` to
|
||||
the VM again, then run the following:
|
||||
|
||||
```bash
|
||||
|
|
@ -169,13 +159,13 @@ Starting a local Treeherder instance
|
|||
|
||||
This will build the UI code and keep watching for new changes.
|
||||
|
||||
* Visit <http://localhost:5000> in your browser (NB: port has changed). Note: There will be no data to display until the ingestion tasks are run.
|
||||
- Visit <http://localhost:5000> in your browser (NB: port has changed). Note: There will be no data to display until the ingestion tasks are run.
|
||||
|
||||
## Building the minified UI with Vagrant
|
||||
|
||||
Building the minified UI with Vagrant
|
||||
-------------------------------------
|
||||
If you would like to view the minified production version of the UI with Vagrant, follow this step:
|
||||
|
||||
* Run the build task (either outside or inside of the Vagrant machine):
|
||||
- Run the build task (either outside or inside of the Vagrant machine):
|
||||
|
||||
```bash
|
||||
$ yarn build
|
||||
|
|
@ -184,13 +174,12 @@ If you would like to view the minified production version of the UI with Vagrant
|
|||
Once the build is complete, the minified version of the UI will now be accessible at
|
||||
<http://localhost:8000> (NB: port 8000, unlike above).
|
||||
|
||||
Validating JavaScript
|
||||
---------------------
|
||||
## Validating JavaScript
|
||||
|
||||
We run our JavaScript code in the frontend through [eslint] to ensure
|
||||
that new code has a consistent style and doesn't suffer from common
|
||||
errors. Eslint will run automatically when you build the JavaScript code
|
||||
or run the development server. A production build will fail if your code
|
||||
or run the development server. A production build will fail if your code
|
||||
does not match the style requirements.
|
||||
|
||||
To run eslint by itself, you may run the lint task:
|
||||
|
|
@ -199,12 +188,11 @@ To run eslint by itself, you may run the lint task:
|
|||
$ yarn lint
|
||||
```
|
||||
|
||||
Running the ingestion tasks
|
||||
---------------------------
|
||||
## Running the ingestion tasks
|
||||
|
||||
Ingestion tasks populate the database with version control push logs, queued/running/completed jobs & output from log parsing, as well as maintain a cache of intermittent failure bugs. To run these:
|
||||
|
||||
* Start up a celery worker to process async tasks:
|
||||
- Start up a celery worker to process async tasks:
|
||||
|
||||
```bash
|
||||
vagrant ~/treeherder$ celery -A treeherder worker -B --concurrency 5
|
||||
|
|
@ -213,10 +201,9 @@ Ingestion tasks populate the database with version control push logs, queued/run
|
|||
The "-B" option tells the celery worker to startup a beat service, so that periodic tasks can be executed.
|
||||
You only need one worker with the beat service enabled. Multiple beat services will result in periodic tasks being executed multiple times.
|
||||
|
||||
* Then in a new terminal window, run `vagrant ssh` again, and follow the steps from the [loading pulse data](pulseload.md) page.
|
||||
- Then in a new terminal window, run `vagrant ssh` again, and follow the steps from the [loading pulse data](pulseload.md) page.
|
||||
|
||||
Ingesting a single push (at a time)
|
||||
-----------------------------------
|
||||
## Ingesting a single push (at a time)
|
||||
|
||||
```eval_rst
|
||||
.. warning::
|
||||
|
|
@ -238,8 +225,7 @@ vagrant ~/treeherder$ ./manage.py ingest_push mozilla-inbound 63f8a47cfdf5
|
|||
If running this locally, replace `63f8a47cfdf5` with a recent revision (= pushed within
|
||||
the last four hours) on mozilla-inbound.
|
||||
|
||||
Ingesting a range of pushes
|
||||
---------------------------
|
||||
## Ingesting a range of pushes
|
||||
|
||||
It is also possible to ingest the last N pushes for a repository:
|
||||
|
||||
|
|
@ -250,22 +236,20 @@ vagrant ~/treeherder$ ./manage.py ingest_push mozilla-central --last-n-pushes 10
|
|||
In this mode, only the pushlog data will be ingested: additional results
|
||||
associated with the pushes will not. This mode is useful to seed pushes so
|
||||
they are visible on the web interface and so you can easily copy and paste
|
||||
changesets from the web interface into subsequent ``ingest_push`` commands.
|
||||
|
||||
changesets from the web interface into subsequent `ingest_push` commands.
|
||||
|
||||
Continue to **Working with the Server** section after looking at the [Code Style](code_style.md) doc.
|
||||
|
||||
|
||||
[A-Team Bootcamp]: https://ateam-bootcamp.readthedocs.io
|
||||
[Git]: https://git-scm.com
|
||||
[Vagrant]: https://www.vagrantup.com
|
||||
[Virtualbox]: https://www.virtualbox.org
|
||||
[a-team bootcamp]: https://ateam-bootcamp.readthedocs.io
|
||||
[git]: https://git-scm.com
|
||||
[vagrant]: https://www.vagrantup.com
|
||||
[virtualbox]: https://www.virtualbox.org
|
||||
[treeherder repo]: https://github.com/mozilla/treeherder
|
||||
[Karma]: http://karma-runner.github.io/0.8/config/configuration-file.html
|
||||
[Jest]: https://jestjs.io/docs/en/tutorial-react
|
||||
[Node.js]: https://nodejs.org/en/download/current/
|
||||
[Yarn]: https://yarnpkg.com/en/docs/install
|
||||
[karma]: http://karma-runner.github.io/0.8/config/configuration-file.html
|
||||
[jest]: https://jestjs.io/docs/en/tutorial-react
|
||||
[node.js]: https://nodejs.org/en/download/current/
|
||||
[yarn]: https://yarnpkg.com/en/docs/install
|
||||
[package.json]: https://github.com/mozilla/treeherder/blob/master/package.json
|
||||
[ESLint]: https://eslint.org
|
||||
[Jasmine]: https://jasmine.github.io/
|
||||
[eslint]: https://eslint.org
|
||||
[jasmine]: https://jasmine.github.io/
|
||||
[enzyme]: http://airbnb.io/enzyme/
|
||||
|
|
|
|||
|
|
@ -1,50 +1,44 @@
|
|||
Loading Pulse data
|
||||
==================
|
||||
# Loading Pulse data
|
||||
|
||||
For ingestion from **Pulse** exchanges, on your local machine, you can choose
|
||||
to ingest from any exchange you like. Some exchanges will be registered in
|
||||
``settings.py`` for use by the Treeherder servers. You can use those to get the
|
||||
same data as Treeherder. Or you can specify your own and experiment with
|
||||
to ingest from any exchange you like. Some exchanges will be registered in
|
||||
`settings.py` for use by the Treeherder servers. You can use those to get the
|
||||
same data as Treeherder. Or you can specify your own and experiment with
|
||||
posting your own data.
|
||||
|
||||
|
||||
The Simple Case
|
||||
---------------
|
||||
## The Simple Case
|
||||
|
||||
If you just want to get the same data that Treeherder gets, then you have 3 steps:
|
||||
|
||||
1. Create a user on [Pulse Guardian] if you don't already have one
|
||||
2. Create your ``PULSE_URL`` string
|
||||
3. Open a Vagrant terminal to read Pushes
|
||||
4. Open a Vagrant terminal to read Jobs
|
||||
5. Open a Vagrant terminal to run **Celery**
|
||||
|
||||
1. Create a user on [Pulse Guardian] if you don't already have one
|
||||
2. Create your `PULSE_URL` string
|
||||
3. Open a Vagrant terminal to read Pushes
|
||||
4. Open a Vagrant terminal to read Jobs
|
||||
5. Open a Vagrant terminal to run **Celery**
|
||||
|
||||
### 1. Pulse Guardian
|
||||
|
||||
Visit [Pulse Guardian], sign in, and create a **Pulse User**. It will ask you to set a
|
||||
username and password. Remember these as you'll use them in the next step.
|
||||
Visit [Pulse Guardian], sign in, and create a **Pulse User**. It will ask you to set a
|
||||
username and password. Remember these as you'll use them in the next step.
|
||||
Unfortunately, **Pulse** doesn't support creating queues with a guest account, so
|
||||
this step is necessary.
|
||||
|
||||
|
||||
### 2. Environment Variable
|
||||
|
||||
If your **Pulse User** was username: ``foo`` and password: ``bar``, your config
|
||||
If your **Pulse User** was username: `foo` and password: `bar`, your config
|
||||
string would be:
|
||||
|
||||
```bash
|
||||
PULSE_URL="amqp://foo:bar@pulse.mozilla.org:5671/?ssl=1"
|
||||
```
|
||||
|
||||
|
||||
### 3. Read Pushes
|
||||
|
||||
```eval_rst
|
||||
.. note:: Be sure your Vagrant environment is up-to-date. Reload it and run ``vagrant provision`` if you're not sure.
|
||||
```
|
||||
|
||||
``ssh`` into Vagrant, then set your config environment variable:
|
||||
`ssh` into Vagrant, then set your config environment variable:
|
||||
|
||||
```bash
|
||||
export PULSE_URL="amqp://foo:bar@pulse.mozilla.org:5671/?ssl=1"
|
||||
|
|
@ -58,15 +52,14 @@ exchange:
|
|||
```
|
||||
|
||||
You will see a list of the exchanges it has mounted to and a message for each
|
||||
push as it is read. This process does not ingest the push into Treeherder. It
|
||||
adds that Push message to a local **Celery** queue for ingestion. They will be
|
||||
push as it is read. This process does not ingest the push into Treeherder. It
|
||||
adds that Push message to a local **Celery** queue for ingestion. They will be
|
||||
ingested in step 5.
|
||||
|
||||
|
||||
### 4. Read Jobs
|
||||
|
||||
As in step 3, open a Vagrant terminal and export your ``PULSE_URL``
|
||||
variable. Then run the following management command:
|
||||
As in step 3, open a Vagrant terminal and export your `PULSE_URL`
|
||||
variable. Then run the following management command:
|
||||
|
||||
```bash
|
||||
./manage.py read_pulse_jobs
|
||||
|
|
@ -75,34 +68,33 @@ variable. Then run the following management command:
|
|||
You will again see the list of exchanges that your queue is now mounted to and
|
||||
a message for each Job as it is read into your local **Celery** queue.
|
||||
|
||||
|
||||
### 5. Celery
|
||||
|
||||
Open your next Vagrant terminal. You don't need to set your environment variable
|
||||
in this one. Just run **Celery**:
|
||||
Open your next Vagrant terminal. You don't need to set your environment variable
|
||||
in this one. Just run **Celery**:
|
||||
|
||||
```bash
|
||||
celery -A treeherder worker -B --concurrency 5
|
||||
```
|
||||
|
||||
That's it! With those processes running, you will begin ingesting Treeherder
|
||||
data. To see the data, you will need to run the Treeherder UI and API.
|
||||
That's it! With those processes running, you will begin ingesting Treeherder
|
||||
data. To see the data, you will need to run the Treeherder UI and API.
|
||||
See [Running the unminified UI with Vagrant] for more info.
|
||||
|
||||
[Running the unminified UI with Vagrant]: ui/installation.html#running-the-unminified-ui-with-vagrant
|
||||
[running the unminified ui with vagrant]: ui/installation.html#running-the-unminified-ui-with-vagrant
|
||||
|
||||
|
||||
Advanced Configuration
|
||||
----------------------
|
||||
## Advanced Configuration
|
||||
|
||||
### Changing which Data to Ingest
|
||||
|
||||
``treeherder.services.pulse.sources`` provides default sources for both Jobs and Pushes.
|
||||
`treeherder.services.pulse.sources` provides default sources for both Jobs and Pushes.
|
||||
|
||||
#### Pushes
|
||||
``push_sources`` defines a list of exchanges with routing keys.
|
||||
|
||||
`push_sources` defines a list of exchanges with routing keys.
|
||||
It's rare you'll need to change this so it's not configurable via the environment.
|
||||
However if you wanted to, say, only get pushes to GitHub you would edit the list to look like this:
|
||||
|
||||
```python
|
||||
push_sources = [
|
||||
"exchange/taskcluster-github/v1/push.#",
|
||||
|
|
@ -110,57 +102,56 @@ push_sources = [
|
|||
```
|
||||
|
||||
#### Jobs
|
||||
Job Exchanges and Projects are defined in ``job_sources``, however can
|
||||
|
||||
Job Exchanges and Projects are defined in `job_sources`, however can
|
||||
also be configured in the environment like so:
|
||||
|
||||
``PULSE_JOB_SOURCES`` defines a list of exchanges with projects.
|
||||
`PULSE_JOB_SOURCES` defines a list of exchanges with projects.
|
||||
|
||||
```bash
|
||||
export PULSE_JOB_SOURCES="exchange/taskcluster-treeherder/v1/jobs.mozilla-central:mozilla-inbound,exchange/fxtesteng/jobs.#",
|
||||
```
|
||||
|
||||
In this example we've defined two exchanges:
|
||||
|
||||
* ``exchange/taskcluster-treeherder/v1/jobs``
|
||||
* ``exchange/fxtesteng/jobs``
|
||||
- `exchange/taskcluster-treeherder/v1/jobs`
|
||||
- `exchange/fxtesteng/jobs`
|
||||
|
||||
The taskcluster-treeherder exchange defines two projects:
|
||||
|
||||
* ``mozilla-central``
|
||||
* ``mozilla-inbound``
|
||||
- `mozilla-central`
|
||||
- `mozilla-inbound`
|
||||
|
||||
The ``fxtesteng`` exchange defines a wildcard (``#``) for its project.
|
||||
|
||||
When Jobs are read from Pulse and added to Treeherder's celery queue we generate a routing key by prepending ``#.`` to each project key.
|
||||
The `fxtesteng` exchange defines a wildcard (`#`) for its project.
|
||||
|
||||
When Jobs are read from Pulse and added to Treeherder's celery queue we generate a routing key by prepending `#.` to each project key.
|
||||
|
||||
### Advanced Celery options
|
||||
|
||||
If you only want to ingest the Pushes and Jobs, but don't care about log parsing
|
||||
and all the other processing Treeherder does, then you can minimize the **Celery**
|
||||
task. You will need:
|
||||
task. You will need:
|
||||
|
||||
```bash
|
||||
celery -A treeherder worker -B -Q pushlog,store_pulse_jobs,store_pulse_resultsets --concurrency 5
|
||||
```
|
||||
|
||||
* The ``pushlog`` queue loads up to the last 10 Mercurial pushes that exist.
|
||||
* The ``store_pulse_resultsets`` queue will ingest all the pushes from the exchanges
|
||||
specified in ``push_sources``. This can be Mercurial and Github
|
||||
* The ``store_pulse_jobs`` queue will ingest all the jobs from the exchanges
|
||||
specified in ``job_sources`` (or ``PULSE_JOB_SOURCES``).
|
||||
- The `pushlog` queue loads up to the last 10 Mercurial pushes that exist.
|
||||
- The `store_pulse_resultsets` queue will ingest all the pushes from the exchanges
|
||||
specified in `push_sources`. This can be Mercurial and Github
|
||||
- The `store_pulse_jobs` queue will ingest all the jobs from the exchanges
|
||||
specified in `job_sources` (or `PULSE_JOB_SOURCES`).
|
||||
|
||||
```eval_rst
|
||||
.. note:: Any job that comes from **Pulse** that does not have an associated push will be skipped.
|
||||
.. note:: It is slightly confusing to see ``store_pulse_resultsets`` there. It is there for legacy reasons and will change to ``store_pulse_pushes`` at some point.
|
||||
```
|
||||
|
||||
## Posting Data
|
||||
|
||||
Posting Data
|
||||
------------
|
||||
|
||||
To post data to your own **Pulse** exchange, you can use the ``publish_to_pulse``
|
||||
management command. This command takes the ``routing_key``, ``connection_url``
|
||||
and ``payload_file``. The payload file must be a ``JSON`` representation of
|
||||
To post data to your own **Pulse** exchange, you can use the `publish_to_pulse`
|
||||
management command. This command takes the `routing_key`, `connection_url`
|
||||
and `payload_file`. The payload file must be a `JSON` representation of
|
||||
a job as specified in the [YML Schema].
|
||||
|
||||
Here is a set of example parameters that could be used to run it:
|
||||
|
|
@ -172,6 +163,6 @@ Here is a set of example parameters that could be used to run it:
|
|||
You can use the handy [Pulse Inspector] to view messages in your exchange to
|
||||
test that they are arriving at Pulse the way you expect.
|
||||
|
||||
[Pulse Guardian]: https://pulseguardian.mozilla.org/whats_pulse
|
||||
[Pulse Inspector]: https://tools.taskcluster.net/pulse-inspector/
|
||||
[YML Schema]: https://github.com/mozilla/treeherder/blob/master/schemas/pulse-job.yml
|
||||
[pulse guardian]: https://pulseguardian.mozilla.org/whats_pulse
|
||||
[pulse inspector]: https://tools.taskcluster.net/pulse-inspector/
|
||||
[yml schema]: https://github.com/mozilla/treeherder/blob/master/schemas/pulse-job.yml
|
||||
|
|
|
|||
|
|
@ -1,23 +1,19 @@
|
|||
REST API
|
||||
========
|
||||
# REST API
|
||||
|
||||
Treeherder provides a REST API which can be used to query for all the
|
||||
push, job, and performance data it stores internally. For a browsable
|
||||
interface, see:
|
||||
<https://treeherder.mozilla.org/docs/>
|
||||
|
||||
Profiling API endpoint performance
|
||||
----------------------------------
|
||||
## Profiling API endpoint performance
|
||||
|
||||
On our development (vagrant) instance we have [django-debug-toolbar](
|
||||
http://django-debug-toolbar.readthedocs.io/) installed, which can give
|
||||
On our development (vagrant) instance we have [django-debug-toolbar](http://django-debug-toolbar.readthedocs.io/) installed, which can give
|
||||
information on exactly what SQL is run to generate individual API
|
||||
endpoints. Just navigate to an endpoint
|
||||
(example: <http://localhost:8000/api/repository/>) and
|
||||
you should see the toolbar to your right.
|
||||
|
||||
Python Client
|
||||
-------------
|
||||
## Python Client
|
||||
|
||||
We provide a library, called treeherder-client, to simplify
|
||||
interacting with the REST API. It is maintained inside the
|
||||
|
|
@ -58,14 +54,12 @@ import logging
|
|||
logging.basicConfig()
|
||||
```
|
||||
|
||||
For verbose output, pass ``level=logging.DEBUG`` to ``basicConfig()``.
|
||||
For verbose output, pass `level=logging.DEBUG` to `basicConfig()`.
|
||||
|
||||
|
||||
User Agents
|
||||
-----------
|
||||
## User Agents
|
||||
|
||||
When interacting with Treeherder's API, you must set an appropriate
|
||||
``User Agent`` header (rather than relying on the defaults of your
|
||||
`User Agent` header (rather than relying on the defaults of your
|
||||
language/library) so that we can more easily track API feature usage,
|
||||
as well as accidental abuse. Default scripting User Agents will receive
|
||||
an HTTP 403 response (see [bug 1230222] for more details).
|
||||
|
|
|
|||
|
|
@ -1,5 +1,4 @@
|
|||
Retrieving Data
|
||||
===============
|
||||
# Retrieving Data
|
||||
|
||||
The [Python client](rest_api.html#python-client) also has some convenience
|
||||
methods to query the Treeherder API.
|
||||
|
|
|
|||
52
docs/seta.md
52
docs/seta.md
|
|
@ -1,5 +1,4 @@
|
|||
SETA
|
||||
====
|
||||
# SETA
|
||||
|
||||
SETA finds the minimum set of jobs to run in order to catch all failures that our automation has found in the recent past on Firefox development repositories.
|
||||
There's one main API that SETA offers consumers (e.g. the Gecko decision task) in order to show which jobs are consider low value
|
||||
|
|
@ -18,45 +17,42 @@ weeks since we don't have historical data to determine how likely they're to cat
|
|||
|
||||
In order to find open bugs for SETA visit list of [SETA bugs].
|
||||
|
||||
[SETA bugs]: https://bugzilla.mozilla.org/buglist.cgi?product=Tree%20Management&component=Treeherder%3A%20SETA&resolution=---
|
||||
[seta bugs]: https://bugzilla.mozilla.org/buglist.cgi?product=Tree%20Management&component=Treeherder%3A%20SETA&resolution=---
|
||||
|
||||
APIs
|
||||
----
|
||||
## APIs
|
||||
|
||||
* `/api/project/{project}/seta/{version}/job-priorities/`
|
||||
- `/api/project/{project}/seta/{version}/job-priorities/`
|
||||
|
||||
* This is the API that consumers like the Gecko decision task will use
|
||||
- This is the API that consumers like the Gecko decision task will use
|
||||
|
||||
* `/api/project/{project}/seta/{version}/job-types/`
|
||||
- `/api/project/{project}/seta/{version}/job-types/`
|
||||
|
||||
* This API shows which jobs are defined for each project
|
||||
- This API shows which jobs are defined for each project
|
||||
|
||||
* `/api/seta/{version}/failures-fixed-by-commit/`
|
||||
- `/api/seta/{version}/failures-fixed-by-commit/`
|
||||
|
||||
* This API shows job failures that have been annotated with "fixed by commit"
|
||||
- This API shows job failures that have been annotated with "fixed by commit"
|
||||
|
||||
Local set up
|
||||
------------
|
||||
## Local set up
|
||||
|
||||
After you set up Treeherder, ssh (3 different tabs) into the provisioned VM and run the following commands in each:
|
||||
|
||||
* 1st tab: ``./manage.py runserver``
|
||||
* 2nd tab: ``yarn start:local``
|
||||
* 3rd tab: ``./manage.py initialize_seta``
|
||||
- 1st tab: `./manage.py runserver`
|
||||
- 2nd tab: `yarn start:local`
|
||||
- 3rd tab: `./manage.py initialize_seta`
|
||||
|
||||
Then try out the various APIs:
|
||||
|
||||
* <http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-priorities/?build_system_type=buildbot>
|
||||
* <http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-priorities/?build_system_type=taskcluster>
|
||||
* <http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-types/>
|
||||
* <http://localhost:5000/api/seta/v1/failures-fixed-by-commit/>
|
||||
- <http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-priorities/?build_system_type=buildbot>
|
||||
- <http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-priorities/?build_system_type=taskcluster>
|
||||
- <http://localhost:5000/api/project/mozilla-inbound/seta/v1/job-types/>
|
||||
- <http://localhost:5000/api/seta/v1/failures-fixed-by-commit/>
|
||||
|
||||
* This one won't work until [bug 1389123] is fixed.
|
||||
- This one won't work until [bug 1389123] is fixed.
|
||||
|
||||
[bug 1389123]: https://bugzilla.mozilla.org/show_bug.cgi?id=1389123
|
||||
|
||||
Maintenance
|
||||
-----------
|
||||
## Maintenance
|
||||
|
||||
Sometimes the default behaviour of SETA is not adequate (e.g. new jobs noticed get a 2 week expiration date & a high priority)
|
||||
when adding new platforms (e.g. stylo).
|
||||
|
|
@ -78,13 +74,13 @@ heroku run --app treeherder-prod -- bash
|
|||
Sometimes, before you can adjust priorities of the jobs, you need to make sure they make it into the JobPriority table.
|
||||
In order to do so we need to:
|
||||
|
||||
* Make sure the scheduling changes have made it into mozilla-inbound
|
||||
- Make sure the scheduling changes have made it into mozilla-inbound
|
||||
|
||||
* SETA uses mozilla-inbound as a reference for jobs for all trunk trees
|
||||
- SETA uses mozilla-inbound as a reference for jobs for all trunk trees
|
||||
|
||||
* Make sure the job shows up in the [runnable jobs API]
|
||||
- Make sure the job shows up in the [runnable jobs API]
|
||||
|
||||
* Update the job priority table from the shell:
|
||||
- Update the job priority table from the shell:
|
||||
|
||||
Open the Python shell using `./manage.py shell`, then enter:
|
||||
|
||||
|
|
@ -106,4 +102,4 @@ In order to do so we need to:
|
|||
JobPriority.objects.filter(platform="windows7-32-stylo", expiration_date__isnull=False).update(expiration_date=None)
|
||||
```
|
||||
|
||||
[runnable jobs API]: https://treeherder.mozilla.org/api/project/mozilla-inbound/runnable_jobs/
|
||||
[runnable jobs api]: https://treeherder.mozilla.org/api/project/mozilla-inbound/runnable_jobs/
|
||||
|
|
|
|||
|
|
@ -1,31 +1,29 @@
|
|||
Submitting Data
|
||||
===============
|
||||
# Submitting Data
|
||||
|
||||
To submit your test data to Treeherder, you have two options:
|
||||
|
||||
1. Using Taskcluster (recommended)
|
||||
|
||||
It's strongly recommended that you schedule jobs using Taskcluster rather
|
||||
than using your own build system, since otherwise many Treeherder features
|
||||
will not work without significant effort, and it's also unlikely your jobs
|
||||
will be eligible for tier 1 or even tier 2 status.
|
||||
It's strongly recommended that you schedule jobs using Taskcluster rather
|
||||
than using your own build system, since otherwise many Treeherder features
|
||||
will not work without significant effort, and it's also unlikely your jobs
|
||||
will be eligible for tier 1 or even tier 2 status.
|
||||
|
||||
2. [Using Pulse](#using-pulse)
|
||||
|
||||
This is the process Taskcluster is using to submit data to Treeherder.
|
||||
There is a [Pulse Job Schema] to validate your payload against to ensure it will
|
||||
be accepted. In this case, you create your own [Pulse] exchange and publish
|
||||
to it. To get Treeherder to receive your data, you would create a bug to
|
||||
have your Exchange added to Treeherder's config. All Treeherder instances
|
||||
can subscribe to get your data, as can local dev instances for testing.
|
||||
This is the process Taskcluster is using to submit data to Treeherder.
|
||||
There is a [Pulse Job Schema] to validate your payload against to ensure it will
|
||||
be accepted. In this case, you create your own [Pulse] exchange and publish
|
||||
to it. To get Treeherder to receive your data, you would create a bug to
|
||||
have your Exchange added to Treeherder's config. All Treeherder instances
|
||||
can subscribe to get your data, as can local dev instances for testing.
|
||||
|
||||
While it is beyond the scope of this document to explain how [Pulse] and
|
||||
RabbitMQ work, we encourage you to read more about this technology on
|
||||
its Wiki page.
|
||||
|
||||
Note: Support for submitting data using Pulse outside of Taskcluster may
|
||||
be removed in the future.
|
||||
While it is beyond the scope of this document to explain how [Pulse] and
|
||||
RabbitMQ work, we encourage you to read more about this technology on
|
||||
its Wiki page.
|
||||
|
||||
Note: Support for submitting data using Pulse outside of Taskcluster may
|
||||
be removed in the future.
|
||||
|
||||
If you are establishing a new repository with Treeherder, then you will need to
|
||||
do one of the following:
|
||||
|
|
@ -34,9 +32,7 @@ do one of the following:
|
|||
|
||||
2. For Mercurial repos: [Add a new Mercurial repository](common_tasks.html#add-a-new-mercurial-repository)
|
||||
|
||||
|
||||
Using Pulse
|
||||
-----------
|
||||
## Using Pulse
|
||||
|
||||
To submit via a Pulse exchange, these are the steps you will need to follow:
|
||||
|
||||
|
|
@ -48,13 +44,12 @@ job group/type symbol, description, log information, etc.
|
|||
You are responsible for validating your data prior to publishing it onto your
|
||||
exchange, or Treeherder may reject it.
|
||||
|
||||
|
||||
### 2. Create your Exchange
|
||||
|
||||
With [Pulse Guardian], you need to create your Pulse User in order to
|
||||
create your own Queues and Exchanges. There is no mechanism to create an
|
||||
Exchange in the Pulse Guardian UI itself, however. You will need to create
|
||||
your exchange in your submitting code. There are a few options available
|
||||
create your own Queues and Exchanges. There is no mechanism to create an
|
||||
Exchange in the Pulse Guardian UI itself, however. You will need to create
|
||||
your exchange in your submitting code. There are a few options available
|
||||
for that:
|
||||
|
||||
1. [MozillaPulse]
|
||||
|
|
@ -62,11 +57,10 @@ for that:
|
|||
3. Or any RabbitMQ package of your choice
|
||||
|
||||
To test publishing your data to your Exchange, you can use the Treeherder
|
||||
management command [publish_to_pulse]. This is also a very simple example
|
||||
management command [publish_to_pulse]. This is also a very simple example
|
||||
of a Pulse publisher using Kombu that you can use to learn to write your own
|
||||
publisher.
|
||||
|
||||
|
||||
### 3. Register with Treeherder
|
||||
|
||||
Once you have successfully tested a round-trip through your Pulse exchange to
|
||||
|
|
@ -87,10 +81,10 @@ Submit a [Treeherder bug] with the following information:
|
|||
```
|
||||
|
||||
Treeherder will bind to the exchange looking for all combinations of it and the
|
||||
``projects``. For example with the above config, we will only load jobs from
|
||||
the ``mozilla-inbound._`` project.
|
||||
`projects`. For example with the above config, we will only load jobs from
|
||||
the `mozilla-inbound._` project.
|
||||
|
||||
If you want all jobs from your exchange to be loaded, you can use the ``#``
|
||||
If you want all jobs from your exchange to be loaded, you can use the `#`
|
||||
wildcard like so:
|
||||
|
||||
```python
|
||||
|
|
@ -100,24 +94,21 @@ wildcard like so:
|
|||
```
|
||||
|
||||
If you want one config to go to Treeherder Staging and a different one to go
|
||||
to Production, please specify that in the bug. You could use the same exchange
|
||||
with different project settings, or two separate exchanges. The choice is
|
||||
to Production, please specify that in the bug. You could use the same exchange
|
||||
with different project settings, or two separate exchanges. The choice is
|
||||
yours.
|
||||
|
||||
|
||||
### 4. Publish jobs to your Exchange
|
||||
|
||||
Once the above config is set on Treeherder, you can begin publishing jobs
|
||||
to your Exchange and they will start showing in Treeherder.
|
||||
|
||||
You will no longer need any special credentials. You publish messages to the
|
||||
Exchange YOU own. Treeherder is now just listening to it.
|
||||
You will no longer need any special credentials. You publish messages to the
|
||||
Exchange YOU own. Treeherder is now just listening to it.
|
||||
|
||||
## Adding a GitHub Repository
|
||||
|
||||
Adding a GitHub Repository
|
||||
--------------------------
|
||||
|
||||
The pushes from GitHub repos come to Treeherder via Pulse. The webhook to enable
|
||||
The pushes from GitHub repos come to Treeherder via Pulse. The webhook to enable
|
||||
this exists in the GitHub group `mozilla`. (For example, `github.com/mozilla/treeherder`)
|
||||
|
||||
The following steps are required:
|
||||
|
|
@ -126,19 +117,19 @@ The following steps are required:
|
|||
`treeherder/model/fixtures/repository.json`
|
||||
|
||||
2. Open a bug request to enable the webhook that will trigger pulse messages for
|
||||
every push from your repo. Use the following information:
|
||||
every push from your repo. Use the following information:
|
||||
|
||||
* Component: GitHub: Administration
|
||||
* Ask to install the <https://github.com/apps/taskcluster> integration on your repositories
|
||||
* List the repositories you want to have access to the integration
|
||||
* Answer: Are any of those repositories private?
|
||||
* State that this is only to get Pulse messages for integration into Treeherder
|
||||
- Component: GitHub: Administration
|
||||
- Ask to install the <https://github.com/apps/taskcluster> integration on your repositories
|
||||
- List the repositories you want to have access to the integration
|
||||
- Answer: Are any of those repositories private?
|
||||
- State that this is only to get Pulse messages for integration into Treeherder
|
||||
|
||||
[Pulse Guardian]: https://pulseguardian.mozilla.org/whats_pulse
|
||||
[Pulse]: https://wiki.mozilla.org/Auto-tools/Projects/Pulse
|
||||
[Pulse Inspector]: https://tools.taskcluster.net/pulse-inspector/
|
||||
[Pulse Job Schema]: https://github.com/mozilla/treeherder/blob/master/schemas/pulse-job.yml
|
||||
[Treeherder bug]: https://bugzilla.mozilla.org/enter_bug.cgi?component=Treeherder:%20Data%20Ingestion&form_name=enter_bug&product=Tree%20Management
|
||||
[MozillaPulse]: https://pypi.python.org/pypi/MozillaPulse
|
||||
[Kombu]: https://pypi.python.org/pypi/kombu
|
||||
[pulse guardian]: https://pulseguardian.mozilla.org/whats_pulse
|
||||
[pulse]: https://wiki.mozilla.org/Auto-tools/Projects/Pulse
|
||||
[pulse inspector]: https://tools.taskcluster.net/pulse-inspector/
|
||||
[pulse job schema]: https://github.com/mozilla/treeherder/blob/master/schemas/pulse-job.yml
|
||||
[treeherder bug]: https://bugzilla.mozilla.org/enter_bug.cgi?component=Treeherder:%20Data%20Ingestion&form_name=enter_bug&product=Tree%20Management
|
||||
[mozillapulse]: https://pypi.python.org/pypi/MozillaPulse
|
||||
[kombu]: https://pypi.python.org/pypi/kombu
|
||||
[publish_to_pulse]: https://github.com/mozilla/treeherder/blob/master/treeherder/etl/management/commands/publish_to_pulse.py#L12-L12
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
Treeherder Test Cases
|
||||
=====================
|
||||
# Treeherder Test Cases
|
||||
|
||||
These tests should be run prior to deploying code changes to the Treeherder production environment.
|
||||
|
||||
Initial page load
|
||||
-----------------
|
||||
## Initial page load
|
||||
|
||||
Load Treeherder. eg.
|
||||
|
||||
* [stage](https://treeherder.allizom.org)
|
||||
* [production](https://treeherder.mozilla.org)
|
||||
- [stage](https://treeherder.allizom.org)
|
||||
- [production](https://treeherder.mozilla.org)
|
||||
|
||||
Depending on your test requirement.
|
||||
|
||||
|
|
@ -25,8 +25,8 @@ Intermittent Failures View logo > Treeherder
|
|||
|
||||
**Expected**: Treeherder loads again, displaying pushes per step 1.
|
||||
|
||||
Check Job details Tab selection
|
||||
-------------------------------
|
||||
## Check Job details Tab selection
|
||||
|
||||
Load Treeherder and select a completed/success job.
|
||||
|
||||
**Expected**: The Job details tab should load by default.
|
||||
|
|
@ -47,8 +47,8 @@ Select a Running job.
|
|||
|
||||
**Expected**: The (empty) Failure summary tab should load.
|
||||
|
||||
Pin a job
|
||||
---------
|
||||
## Pin a job
|
||||
|
||||
Select a job, and click the 'pin' button in the lower navbar.
|
||||
|
||||
**Expected**: Selected job pinned
|
||||
|
|
@ -61,29 +61,31 @@ Pinboard > Right hand menu dropdown > Clear all
|
|||
|
||||
**Expected**: Both jobs are removed from the pinboard.
|
||||
|
||||
Failure summary tab
|
||||
-------------------
|
||||
## Failure summary tab
|
||||
|
||||
Select a classified or unclassified failed job.
|
||||
|
||||
**Expected**: Ensure the Failure summary tab loads by default.
|
||||
|
||||
If a Bug suggestion is present in the failure summary:
|
||||
|
||||
* Click on the bug description link
|
||||
* Click on the bug pin icon
|
||||
- Click on the bug description link
|
||||
- Click on the bug pin icon
|
||||
|
||||
**Expected**:
|
||||
* Bug description link should load the correct BMO bug in a new tab
|
||||
* Pin should pin the job and add the bug to the bug classification field
|
||||
|
||||
- Bug description link should load the correct BMO bug in a new tab
|
||||
- Pin should pin the job and add the bug to the bug classification field
|
||||
|
||||
Pinboard > Right hand dropdown menu > Clear all
|
||||
|
||||
**Expected**:
|
||||
* The job should be removed from the Pinboard
|
||||
* The bug number should be cleared from the bug classification field
|
||||
|
||||
Similar jobs tab
|
||||
----------------
|
||||
- The job should be removed from the Pinboard
|
||||
- The bug number should be cleared from the bug classification field
|
||||
|
||||
## Similar jobs tab
|
||||
|
||||
Select a job, select the Similar jobs tab, wait several seconds.
|
||||
|
||||
**Expected**: Recent jobs with matching symbols should load.
|
||||
|
|
@ -96,25 +98,25 @@ Scroll to the bottom of the Similar jobs tab, click 'Show previous jobs'.
|
|||
|
||||
**Expected**: Additional, older jobs with matching symbols should load.
|
||||
|
||||
Job details pane
|
||||
----------------
|
||||
## Job details pane
|
||||
|
||||
Select any job and confirm the following loads in the bottom left pane:
|
||||
|
||||
* Job:
|
||||
* Task: (test this link)
|
||||
* Machine name: (test this link) (this may not exist for taskcluster jobs)
|
||||
* Build: (test this link) (this may not be a link for taskcluster jobs)
|
||||
* Job name:
|
||||
* Requested:
|
||||
* Started: (only present for jobs in either running or completed states)
|
||||
* Ended: (only present for jobs in a completed state)
|
||||
* Duration:
|
||||
* Log parsing status:
|
||||
- Job:
|
||||
- Task: (test this link)
|
||||
- Machine name: (test this link) (this may not exist for taskcluster jobs)
|
||||
- Build: (test this link) (this may not be a link for taskcluster jobs)
|
||||
- Job name:
|
||||
- Requested:
|
||||
- Started: (only present for jobs in either running or completed states)
|
||||
- Ended: (only present for jobs in a completed state)
|
||||
- Duration:
|
||||
- Log parsing status:
|
||||
|
||||
**Expected**: Values load, are visible and correct, and links are valid.
|
||||
|
||||
Classify a job with associated bugs
|
||||
-----------------------------------
|
||||
## Classify a job with associated bugs
|
||||
|
||||
Select and pin 3 jobs to the pinboard, select a classification type, add a classification comment and add bug 1164485. Select 'Save' in the pinboard.
|
||||
|
||||
**Expected**: The jobs show with an asterisk in the job table, green notification banners appear confirming successful classification for each job.
|
||||
|
|
@ -131,8 +133,8 @@ Reload the page.
|
|||
|
||||
**Expected**: The job should still be unclassified.
|
||||
|
||||
Switch repos
|
||||
------------
|
||||
## Switch repos
|
||||
|
||||
Click on the Repos menu, select a different repo.
|
||||
|
||||
**Expected**: The new repo and its pushes should load.
|
||||
|
|
@ -141,14 +143,14 @@ Reverse the process, and switch back.
|
|||
|
||||
**Expected**: The original repo and pushes should load.
|
||||
|
||||
Toggle unclassified failures
|
||||
----------------------------
|
||||
## Toggle unclassified failures
|
||||
|
||||
Load Treeherder and click on the "(n) unclassified" button in the top navbar.
|
||||
|
||||
**Expected**: Only unclassified failures should be visible in the job table.
|
||||
|
||||
Filters panel
|
||||
-------------
|
||||
## Filters panel
|
||||
|
||||
Click and open the 'Filters' menu panel in the top navbar, and turn off several job types in the panel.
|
||||
|
||||
**Expected**: Job types turned off are suppressed in the job table.
|
||||
|
|
@ -161,8 +163,8 @@ Filters panel > Field Filters > click new. Add a new filter eg. Platform, Linux.
|
|||
|
||||
**Expected**: Only Linux platforms should be visible in the job table.
|
||||
|
||||
Filter by Job details name and signature
|
||||
----------------------------------------
|
||||
## Filter by Job details name and signature
|
||||
|
||||
Select any job and in the lower left panel, click on the Job: keywords eg. "Linux x64 asan Mochitest Chrome"
|
||||
|
||||
**Expected**: Ensure only jobs containing those keywords are visible.
|
||||
|
|
@ -171,8 +173,8 @@ Select any job and click on the adjacent "(sig)" signature link.
|
|||
|
||||
**Expected**: Ensure only jobs using that unique signature SHA are visible.
|
||||
|
||||
Pin all visible jobs in push
|
||||
----------------------------
|
||||
## Pin all visible jobs in push
|
||||
|
||||
Click on the Pin 'all' pin-icon in the right hand side of any push bar.
|
||||
|
||||
**Expected**: Up to a maximum of 500 jobs should be pinned, and a matching notification warning should appear if that limit is reached.
|
||||
|
|
@ -181,8 +183,8 @@ Click in the pinboard on the extreme right hand drop down menu, and select 'Clea
|
|||
|
||||
**Expected**: All jobs should be removed from the pinboard.
|
||||
|
||||
Login / Logout
|
||||
--------------
|
||||
## Login / Logout
|
||||
|
||||
Login via Taskcluster Auth.
|
||||
|
||||
**Expected**: The login button should switch to a generic "Person" avatar, and the user email should appear on hover.
|
||||
|
|
@ -191,8 +193,8 @@ Logout
|
|||
|
||||
**Expected**: The login button should switch back to "Login / Register".
|
||||
|
||||
View the Logviewer
|
||||
------------------
|
||||
## View the Logviewer
|
||||
|
||||
Select any failed job and click the 'Log' icon in the lower navbar.
|
||||
|
||||
**Expected**: The Logviewer loads in a new tab, and it contains correct job and revision information in the top left corner, and it preloads and scrolls to the first failure line if one exists.
|
||||
|
|
@ -216,14 +218,14 @@ Select Treeherder from the nav menu.
|
|||
|
||||
**Expected**: Treeherder should load in the same window.
|
||||
|
||||
View the raw log
|
||||
----------------
|
||||
## View the raw log
|
||||
|
||||
Select any completed job and click the raw log button in the lower navbar.
|
||||
|
||||
**Expected**: The raw log for that job should load in a new tab.
|
||||
|
||||
View pushes by Author
|
||||
---------------------
|
||||
## View pushes by Author
|
||||
|
||||
Click on the Author email (eg. ryanvm@gmail.com) in a push bar.
|
||||
|
||||
**Expected**: Only pushes pushed by that Author should appear.
|
||||
|
|
@ -232,8 +234,8 @@ Get next 10| pushes via the main page footer.
|
|||
|
||||
**Expected**: Only pushes from that Author should be added.
|
||||
|
||||
View a single push
|
||||
------------------
|
||||
## View a single push
|
||||
|
||||
Load Treeherder and click on the 'Date' on the left side of any push.
|
||||
|
||||
**Expected**: Only that push should load, with an accompanying URL param "&revision=(SHA)"
|
||||
|
|
@ -242,8 +244,8 @@ Load Treeherder and click on the 'Date' on the left side of any push.
|
|||
|
||||
**Expected**: Only newly started jobs for that same push (if any have occurred) should appear. No new pushes should load.
|
||||
|
||||
Quick Filter input field
|
||||
------------------------
|
||||
## Quick Filter input field
|
||||
|
||||
Click the 'Filter platforms & jobs' input field in the top navbar, aka. Quick Filter.
|
||||
|
||||
**Expected**: Input field should expand in width for long input.
|
||||
|
|
@ -256,16 +258,16 @@ Click the grey (x) 'Clear this filter' icon the right hand side of the input fie
|
|||
|
||||
**Expected**: Filter should be cleared and input should shrink to original width.
|
||||
|
||||
Check push actions menu
|
||||
-----------------------
|
||||
## Check push actions menu
|
||||
|
||||
From any push bar, select each entry in the far right dropdown that doesn't involve retriggers. eg:
|
||||
|
||||
Mark with Bugherder
|
||||
|
||||
**Expected**: Each should open without error or hanging.
|
||||
|
||||
Get next 10|20|50 pushes
|
||||
------------------------
|
||||
## Get next 10|20|50 pushes
|
||||
|
||||
Click on Get next 10| pushes.
|
||||
|
||||
**Expected**: Ensure exactly 10 additional pushes were loaded.
|
||||
|
|
@ -278,8 +280,8 @@ View a single push via its Date link. Click Get next 10| pushes.
|
|||
|
||||
**Expected**: Ensure the page loads the 10 prior pushes and the "tochange" and "fromchange" in the url appear correct.
|
||||
|
||||
Filter pushes by URL fromchange, tochange
|
||||
-----------------------------------------
|
||||
## Filter pushes by URL fromchange, tochange
|
||||
|
||||
See also the Treeherder [userguide] for URL Query String Parameters. Please test variants and perform exploratory testing as top/bottom of range is new functionality (Jun 3, 15')
|
||||
Navigate to the 2nd push loaded, from the push action menu select 'Set as top of range'.
|
||||
|
||||
|
|
@ -297,8 +299,8 @@ Click Get Next | 10 in the page footer.
|
|||
|
||||
**Expected**: Updates should only occur for the visible pushes. No new pushes should appear.
|
||||
|
||||
Filter pushes by URL date range
|
||||
-------------------------------
|
||||
## Filter pushes by URL date range
|
||||
|
||||
See also the Treeherder [userguide] for URL Query String Parameters
|
||||
Add a revision range to the URL in the format, eg:
|
||||
|
||||
|
|
@ -312,8 +314,8 @@ Warning: With the latest volume of jobs and pushes, anything greater than a sing
|
|||
|
||||
**Expected**: pushes loaded should continue to honor that range.
|
||||
|
||||
Perfherder Graphs
|
||||
-----------------
|
||||
## Perfherder Graphs
|
||||
|
||||
Load Perfherder at eg.
|
||||
<https://treeherder.allizom.org/perf.html>
|
||||
|
||||
|
|
@ -331,15 +333,15 @@ Change display range dropdown to 90 days (or other value)
|
|||
|
||||
**Expected**: Ensure both series expand to that date range. Confirm the data which has expired beyond the 6 week data cycle still appears, but the SHA just will instead display "loading revision".
|
||||
|
||||
No console errors throughout test run
|
||||
-------------------------------------
|
||||
## No console errors throughout test run
|
||||
|
||||
Ensure the browser console is error free during and after the test run.
|
||||
Open the console during the test run.
|
||||
|
||||
**Expected**: No errors should appear in the console.
|
||||
|
||||
Perfherder Compare
|
||||
------------------
|
||||
## Perfherder Compare
|
||||
|
||||
Load Perfherder Compare at eg.
|
||||
<https://treeherder.allizom.org/perf.html#/comparechooser>
|
||||
|
||||
|
|
@ -357,14 +359,14 @@ Click on the 'Graph' link for a sub-compare row if it exists.
|
|||
|
||||
**Expected**: The plotted graph for that series should appear.
|
||||
|
||||
All keyboard shortcuts
|
||||
----------------------
|
||||
## All keyboard shortcuts
|
||||
|
||||
Check all keyboard shortcut functionality as listed in the [userguide].
|
||||
|
||||
**Expected**: Each shortcut should work as expected.
|
||||
|
||||
Job counts
|
||||
----------
|
||||
## Job counts
|
||||
|
||||
In any push with job counts, click on the group button eg. B( ) to expand the count.
|
||||
|
||||
**Expected**: Jobs should appear.
|
||||
|
|
|
|||
|
|
@ -1,18 +1,16 @@
|
|||
Troubleshooting
|
||||
===============
|
||||
# Troubleshooting
|
||||
|
||||
Errors during Vagrant setup
|
||||
---------------------------
|
||||
## Errors during Vagrant setup
|
||||
|
||||
* The Vagrant provisioning process during ``vagrant up --provision`` assumes the presence of a stable internet connection. In the event of a connection interruption during provision, you may see errors similar to *"Temporary failure resolving.."* or *"E: Unable to fetch some archives.."* after the process has completed. In that situation, you can attempt to re-provision using the command:
|
||||
- The Vagrant provisioning process during `vagrant up --provision` assumes the presence of a stable internet connection. In the event of a connection interruption during provision, you may see errors similar to _"Temporary failure resolving.."_ or _"E: Unable to fetch some archives.."_ after the process has completed. In that situation, you can attempt to re-provision using the command:
|
||||
|
||||
```bash
|
||||
> vagrant provision
|
||||
```
|
||||
|
||||
If that is still unsuccessful, you should attempt a ``vagrant destroy`` followed by another ``vagrant up --provision``.
|
||||
If that is still unsuccessful, you should attempt a `vagrant destroy` followed by another `vagrant up --provision`.
|
||||
|
||||
* If you encounter an error saying *"mount.nfs: requested NFS version or transport protocol is not supported"*, you should restart the kernel server service using this sequence of commands:
|
||||
- If you encounter an error saying _"mount.nfs: requested NFS version or transport protocol is not supported"_, you should restart the kernel server service using this sequence of commands:
|
||||
|
||||
```bash
|
||||
systemctl stop nfs-kernel-server.service
|
||||
|
|
@ -21,11 +19,11 @@ Errors during Vagrant setup
|
|||
systemctl start nfs-kernel-server.service
|
||||
```
|
||||
|
||||
* If you encounter an error saying:
|
||||
- If you encounter an error saying:
|
||||
|
||||
> *"The guest machine entered an invalid state while waiting for it to boot.
|
||||
> _"The guest machine entered an invalid state while waiting for it to boot.
|
||||
> Valid states are 'starting, running'. The machine is in the 'poweroff' state.
|
||||
> Please verify everything is configured properly and try again."*
|
||||
> Please verify everything is configured properly and try again."_
|
||||
|
||||
...you should check your host machine's virtualization technology (vt-x) is enabled
|
||||
in the BIOS (see this [guide]), then continue with `vagrant up --provision`.
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче