/big-map-registry

Registry for BIG-MAP apps and codes.

Primary LanguagePythonMIT LicenseMIT

BIG-MAP Application Registry

This repository contains the source code of the official app registry for the BIG-MAP project.

Adding an app to the registry

Apps are added to the registry by adding an entry to the apps.yaml file within this repository.

Feel free to propose a new app category to be added to category.yaml before or after adding your app.

  1. Create a pull request to this repository that adds a new entry to the apps.yaml file, e.g., by editing the file directly in the browser. Example:

    my-big-map-app:
  metadata:
    title: MyBIG-MAP app
    description: |
        My BIG-MAP app helps to promote accelerated discovery
        of novel battery materials.
    authors: A. Doe, B. Doe
    external_url: http://my-app.example.com
    documentation_url: https://my-big-map-app.readthedocs.io
    logo: https://github.com/my-org/my-big-map-app/raw/main/logo.png
    state: development
    version: '1.1'
  categories:
    - technology-aiida
    - technology-ase
    - quantum

    Note: Only the metadata fields title and description are mandatory.

  2. Your app will show up in the BIG-MAP App Store once your pull request is approved and merged.

Tip: The app store supports the $ref syntax to reference externally hosted documents. That means you can reference metadata that is hosted at a different location, which makes it easier to dynamically update it. For example, if you place a metadata.yaml file within your app repository, then you can reference that file in the app store like this:

my-big-map-app:
  metadata:
    $ref: https://github.com/my-org/my-big-map-app/raw/main/metadata.yaml

You can even reference only parts of the metadata, example:

my-big-map-app:
  metadata:
    title: MyBIG-MAP app
    description:
      $ref: https://github.com/my-org/my-big-map-app/raw/main/metadata.yaml#description

The app store will assume that external references are in JSON format unless the referenced path ends with .yaml or .yml.

Valid keys for app entries in apps.yaml

Key Requirement Description
metadata Mandatory General description of the app (see below).
categories Optional If provided, must be one of the valid categories specified in categories.yaml](https://github.com/big-map/big-map-registry/blob/main/categories.yaml).
git_url Optional Link to the source code git repository.

Valid keys for app metadata:

Key Requirement Description
title Mandatory The title will be displayed in the list of apps in the application manager.
description Mandatory The description will be displayed on the detail page of your app.
authors Optional Comma-separated list of authors.
logo Optional Absolute path to a logo (png or jpg) within your repository.
state Optional One of
- registered: lowest level - app may not yet be in a working state. Use this to secure a specific name.
- development: app is under active development, expect the occasional bug.
- stable: app can be used in production.
documentation_url Optional The link to the online documentation of the app (e.g. on Read The Docs).
external_url Optional General homepage for your app.

Acknowledgements

This project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 957189.