devtools-device-data/contributing.md

Contributing

Requirements

You need to have Python 2.7 installed with jsonschema. The easy way to install the jsonchema package is through pip. This is achieved with the following command from the repository root:

pip install -r 'requirements.txt'

Note: You may need to run the pip installation as root using sudo or similar methods.

Which branch?

Please submit all requests against the master branch.

Add a new device

1. Add a new folder that follows the naming contention
2. In that folder add a device.json file that fulfills the required scheme.
3. To verify your device will be properly see test changes.
4. Submit a pull request.

Update an existing device

Modify the existing devices.json file to reflect the latest correct information about a device. Then test the changes before submitting a pull request.

Folder naming convention

Folders for device information follow this naming pattern: {vendor}-{device}-{version}. For example:

• Google Nexus 7 - google-nexus-7
• Samsung Galaxy S4 - samsung-galaxy-s4

What not to commit

Do not commit the devices.json file in the root folder. Other than this one limitation, you may submit edits to any other files.

If you have added the file to be commited already, you can do git reset devices.json to remove it from the add. If you have already commited the addition, then you will need to modify the commit.

Scheme

The following are allowed properties within a device.json file.

• type should be one of the phone, tablet, notebook, desktop, unknown;
• capabilities should listen enabled capabilities for the device (currently supported: mobile, touch);
• screen describes the physical device screen size and dpr in horizontal and vertical orientations;
• outline provides an image to draw around the screen;
• modes represent different browser states on the screen (e.g. with/without on-screen keyboard);
• page-rect is the rect relative to the screen size (see above), where web page is displayed; this rect will be emulated;
• title values should be user-readable.

All sizes in should be in device independent pixels

The following code sample is a minimum viable device.json:

{
    "title": "My Awesome Device",
    "type": "notebook",
    "screen": {
        "horizontal": {
            "width": 1024, 
            "height": 968
        }, 
        "device-pixel-ratio": 1, 
        "vertical": {
            "width": 968, 
            "height": 1024
        }
    },
    "user-agent": "Latest UA for given device",
    "show-by-default": false
}

Test changes

To test that your changes will work run generate_devices_list.py.