The projects file

An important part of the information provided to Mordred is the list of projects to analyze, and how they are structured in repositories. This is done in the projects file.

The projects file is a JSON file with the following structure:

{
    "Project1": {
        "datasource1": [ list_of_repos_11 ],
        "datasource2": [ list_of_repos_12 ],
        ...
        "datasourcen": [ list_of_repos_1n ]
    },
    "Project2": {
        ...
    },
    ...
    "Projectk": {
    }
}

That is, in Python terms it is a dictionary of projects, where the key for each project is the project name (as we want it to appear in the dashboard), and the value is a dictionary with the data sources for that project.

In turn the dictionary with data sources has as keys the Perceval identifiers for the data sources of interest for the project (for example “git”, “github”, “jira”, etc.). Values of that dictionary is a list of repositories, also in the format expected by Perceval. See perceval --help, or the main Perceval README for a complete list of data sources supported, and their identifiers. For convenience, this is a close-to-complete list:

askbot: Questions and answers from Askbot site
bugzilla: Bugzilla server
bugzillarest: Bugzilla server (>=5.0) using its REST API
confluence: Confluence server
discourse: Discourse site
gerrit: Gerrit server
git: Commits from Git
github: Issues and PRs from GitHub
gmane: Gmane messages (not working now)
hyperkitty: Messages from a HyperKitty archiver
jenkins: Builds data from a Jenkins server
jira: Issues data from JIRA issue tracker
mbox: Messages from MBox files
mediawiki: Pages and revisions from a MediaWiki site
meetup: Events from a Meetup group
nntp: Articles from a NNTP news group
phabricator: Tasks from a Phabricator site
pipermail: Messages from a Pipermail archiver
redmine: Issues data from a Redmine server
rss: Entries from a RSS feed server
slack: Messages from a Slack channel
stackexchange: Questions, answers and comments from StackExchange sites
supybot: Messages from Supybot log files
telegram: Messages from the Telegram server

As an example, this is an excerpt of the projects file for the CHAOSS dashboard:

{
    "GrimoireLab": {
        "git": [
            "https://github.com/chaoss/grimoirelab-kingarthur",
            "https://github.com/chaoss/grimoirelab-elk",
            "https://github.com/chaoss/grimoirelab-sirmordred",
            ...
        ],
        "github": [
            "https://github.com/chaoss/grimoirelab-kingarthur",
            "https://github.com/chaoss/grimoirelab-elk",
            "https://github.com/chaoss/grimoirelab/mordred",
            ...
        ],
        "pipermail": [
            "https://lists.linuxfoundation.org/pipermail/grimoirelab-discussions"
        ]
    },
    "GHData": {
        "git": [
            "https://github.com/OSSHealth/ghdata"
        ],
        "github": [
            "https://github.com/OSSHealth/ghdata"
        ]
    },
    ...
}

Note that for GitHub repos, we need entries both for “git” and “github”, since two different Perceval backends are used: the first one for the git repository, the second one for GitHub issues and pull requests.

Once we have completed the file, we have to specify its name in the mordred.cfg file (section “projects”, parameter “projects_file”). For example, if the file is /home/user/projects.json, the lines in mordred.cfg would be:

[projects]
projects_file = /home/user/projects.json