Skip to content

GUIDE.md

Latest commit

 

History

History
128 lines (93 loc) · 3.56 KB

GUIDE.md

File metadata and controls

128 lines (93 loc) · 3.56 KB

Guide on how to monitor decomp progress using frogress

Overview

This guide will provide a flow for how to use frogress for your project.

sequenceDiagram
    autonumber
    actor Contributor as Project contributor
    actor Monitor as Spectator
    Contributor->>+CI: Trigger
    CI->>CI: Build
    CI->>CI: Calculate progress
    CI->>-frogress: Upload progress
    Note over CI,frogress: POST /data/project:/version:/
    Monitor->>frogress: Fetch progress
    Note over Monitor,frogress: GET /data/project:/version:/?mode=all
    frogress->>Monitor: Return progress
    Monitor->>Monitor: Render progress
Loading

CI: Continuous Integration services including GitHub Actions, Gitlab pipelines, Travis CI and Jenkins.

Steps

  1. Contact frogress admin (Ethan) to add your project to the database and obtain an api_key

  2. Create schema with cli.py

    2.1 Edit cli.ini

    [frogress]
domain = https://progress.deco.mp
api_key = api_key

    2.2 Create version

    # Usage
./cli.py create version -h
# Example
./cli.py create version fireemblem8 us

    2.3 Create category

    # Usage
./cli.py create category -h
# Example
./cli.py create category fireemblem8 us default

  3. Configure CI to upload data on build

    3.1 API

    POST https://progress.deco.mp/data/project:/version:/

    {
    "api_key": "",
    "entries": [
        "git_hash": "",
        "timestamp": "",
        "categories": {
            "default": {
                # metrics
            }
        }
    ]
}

    3.2 Example

    FireEmblemUniverse/fireemblem8u#307

  4. Supplement historical data (optional, one-time)

    Calculate progress for historical commits and upload it to frogress for the purpose of visualizing and tracking historical data

    Example

  5. Fetch project data

    5.1 API

    There are 3 "modes" for returning results: all, latest, and shield. The first two are pretty self explanatory, and shield can be used to generate badges for your repo's README.md (shields.io).

    GET https://progress.deco.mp/data/project:/version:/?mode=all

    GET https://progress.deco.mp/data/project:/version:/?mode=latest

    Note that the category and measure are required for mode shield.

    GET https://progress.deco.mp/data/project:/version:/category:/?mode=shield&measure=MEASURE

    Note: Specifying a category in the request URL is optional for all and latest modes. If the category is not specified, results from all categories will be returned. However, for shield, it is necessary to specify the category and measure in the request url, as shown above.

    all example:

    https://progress.deco.mp/data/fireemblem8/us/?mode=all

    shield example:

    https://progress.deco.mp/data/dukezh/us/default/?mode=shield&measure=bytes

    5.2 Build a website

    Build a website to display your progress!

    You can use the "latest" mode to retrieve just the latest datapoint or render full graphs using a library such as uPlot or Chart.js