3.6 KiB

Guide on how to monitor decomp progress using frogress


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

    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

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


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

  2. Create schema with

    2.1 Edit cli.ini

    domain =
    api_key = api_key

    2.2 Create version

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

    2.3 Create category

    # Usage
    ./ create category -h
    # Example
    ./ create category fireemblem8 us default
  3. Configure CI to upload data on build

    3.1 API

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

    3.2 Example

  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


  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 (


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


    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:

    shield example:

    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