Skip to content

Architecture

Jump to bottom Edit New page
Ksenia edited this page May 29, 2019 · 10 revisions

Short Introduction

  • GitHub is used for recording issues
  • Flask for the main backend operation
  • A layer of JavaScript to handle the JSON data

The simplified graphical version looks a bit like this:

http-diagram

@startuml
Browser -> webcompat: HTTP Request [by JS on client]
webcompat -> Browser: HTTP Response (html/css/js/images)
Browser -> "webcompat API": HTTP XHR Request [by JS on client]
"webcompat API" -> "GitHub API": HTTP Request [by Python]
"GitHub API" -> "webcompat API": HTTP Response (json)
"webcompat API" -> Browser: HTTP Response (json) [by Python on server]
@enduml

API description

There are two different post to create a new bug report on webcompat.com. Both cases involves that the user accepts through a final step to create the issue. This is important for privacy reasons.

URL with parameter (Deprecated)

It takes basically an API with parameters URL

https://webcompat.com/issues/new?src=desktop-reporter&label=type-media&label=type-stylo&url=https://url.example.com/

will return an HTML page pre-populated with parameters ready to be submitted by the user.

HTTP POST with a JSON body (Recommended)

POST /issues/new HTTP/1.1
Accept: application/json, */*
Content-Length: 45
Content-Type: application/json
User-Agent: something

{
    "src": "web", 
    "url": "https://example.com/"
}

The list of acceptable keywords is the same than in the case of URL parameters. This will return a web page pre-populated with parameters that the user can submit.

HTTP/1.1 200 OK

Authorized keys for submitting bug reports

(2019-01-10 In progress. This will disappear when we finished documenting all the keys.)

"Status: Mandatory" here means that the parameter is required for the form to be submitted by the user even if not given initially by the reporter client.

  • url: The URL of the page being reported.
    • Status: Mandatory
    • Constraints: string. No leading or trailing space. Starts with http or https.
    • Example: "url": "https://twitter.com/search?f=tweets&vertical=default&q=%40webcompat&src=typd"
  • src: The source of the report
    • Status: Mandatory
    • Constraints: string. Controlled list of keywords (see #2546)
      • desktop-reporter (from the report site issue button on Desktop)
      • mobile-reporter (from the report site issue button on Android)
      • addon-reporter (from webcompat addon install)
      • web (directly from the website)
    • Effects: Add a <!-- @reported_with: desktop-reporter --> inside the GitHub issue body.
    • Example: "src": "desktop-reporter"
  • description: A short summary of the issue
    • Status: Mandatory
    • Constraints: string. Will be limited to n characters (see #2629)
    • Example: "description": "The round button for the chinese language selector is broken"
  • problem_type: category of issues
    • Status: Mandatory
    • Constraints: string. One of these keys:
      • detection_bug: Desktop site instead of mobile site
      • site_bug: Site is not usable
      • layout_bug: Design is broken
      • video_bug: Video or audio doesn't play
      • unknown_bug: Something else
    • Example: "problem_type": "unknown_bug"
  • extra_labels: (HTTP POST only. JSON Payload) labels used to qualify the project
    • Status: Optional
    • Constraints: Array.
    • Effects: Add a series of labels to the issue
    • Example: "extra_labels": ["type-media", …]
  • label: (HTTP GET only. URL parameter) label used to qualify the project
    • Status: Optional
    • Constraints: string.
    • Effects: Add this specific label to the issue
    • Example: &label=type-fastclick
  • steps_reproduce: long description on how to reproduce the bug.
    • Status: Optional
    • Constraints: string. Markdown ok.
    • Example: "steps_reproduce": "blah blah"
  • browser: os name
  • os: OS name

Issue body sent to GitHub for storage

This is an example of issue body as posted on GitHub by webcompat.com (slightly modified for the example).

<!-- @browser: Firefox 63.0 -->
<!-- @ua_header: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.13; rv:62.0) Gecko/20100101 Firefox/62.0 -->
<!-- @reported_with: desktop-reporter -->
<!-- @extra_labels: type-stylo, type-media -->

**URL**: http://penang-hokkien.gitlab.io/

**Browser / Version**: Firefox 63.0
**Operating System**: Mac OS X 10.13
**Tested Another Browser**: Yes

**Problem type**: Design is broken
**Description**: The round button for the chinese language selector is broken
**Steps to Reproduce**:
1. Go to http://penang-hokkien.gitlab.io/
2. Just look at the button.

* Firefox and Safari at first load display an oval on the side.
* Chrome gets it right at first load.
* Firefox gets it right if resizing the window (repaint)
* Safari never changes.

Screenshot:
Top Firefox
Middle Safari
Bottom Chrome
[![Screenshot Description](https://webcompat.com/uploads/2018/7/a9c661df-5edf-4ac6-94a5-7b314ff1d09a-thumb.jpg)](https://webcompat.com/uploads/2018/7/a9c661df-5edf-4ac6-94a5-7b314ff1d09a.jpg)



_From [webcompat.com](https://webcompat.com/) with ❤️_

Webhook

Webcompat-bot is the main customer of the webhook system. Each time a new issue is created, webcompat-bot will assign labels and milestones to the issue, depending on a certain number of parameters.

  • URI parameters assign labels
  • new issue created goes automatically to triage.
  • User Agent detection assign browser labels.

Webcompat-bot

Webcompat-bot is here to help with:

  • automatic labeling
  • handling anonymous bug reporting.

Flask + JS

The site currently delivers mostly empty HTML templates containing JavaScript. Once a page is delivered on a HTTP request /issues/[number], a JavaScript fetch is executed to get both the issue description and the associated comments with it. These are sent with a JSON format. Then the page is rendered with this JSON information reformatted on the fly into HTML.

Add a custom footer
Add a custom sidebar
Clone this wiki locally