Publish your AiiDAlab app — aiidalab documentation

Prepare the app for registration

Important

If the app was created with the app cookiecutter it should already have all necessary information and this step can be skipped.

In preparation of registering your AiiDAlab app in the AiiDAlab registry, ensure you have a valid and updated setup.cfg file in the root of your app’s repository. The setup.cfg file can alternatively also be placed within a hidden .aiidalab/ directory in which case it will be parsed with precedence.

AiiDAlab parses the setup.cfg file for metadata and will recognize fields both from the standard [metadata] section and a dedicated [aiidalab] section (fields declared within the [aiidalab] section take precedence). We suggest using the [aiidalab] section only for the title and categories fields, and the [metadata] for all others.

List of all recognized keys and their correspondence (where applicable) between the [metadata] and the [aiidalab] sections.

[aiidalab]	[metadata]	required	description
title	n/a 1	yes	A human-readable title for the app.
description	description	yes	A brief description of the app’s purpose and function.
authors	author	no	A list of all contributing authors.
version	version	no	A version specifier. 2
external_url	url	no	A URL for the app home page.
documentation_url	project_urls: documentation	no	A URL for the app’s documentation, e.g., a README file.
logo	project_urls: logo	no	A URL for the app’s logo.
state 3	from classifiers 4	no	A classification of the app’s development state.
categories	n/a 5	no	Categories under which the app will be listed.

1: The title cannot be declared within the [metadata] section.
2: If an app is automatically released from git tags, the registry will use the tag as a version identifier instead.
3: The app state must be one of [“registered”, “development”, “stable”].
4: The development state is parsed from the Development State trove classifiers and automatically mapped to the AiiDAlab development states.
5: The categories cannot be declared within the [metadata] section. The complete list of valid categories can be found here.

Tip

Use the aiidalab registry parse-app-repo command to test what metadata would be parsed from your app repository.

Example: aiidalab registry parse-app-repo ~/apps/my-app.

Register the app

The app registry uses a pull approach, meaning it regularly scans the registered app repositories for new releases. 6 This is to simplify the release procedure for app developers. For example, typically an app developer will register an app such that newly created tags on a dedicated git branch are automatically released to users.

To register an app, simply edit the apps.yaml file on GitHub by clicking on the icon in the top right corner and add an entry for your app according to one of the approaches shown below.

Releases are specified in the form of a list, where each list entry corresponds to one or more tagged commits of a git repository branch. In case that it corresponds to multiple commits, the release entry is called a release line.

Release all tagged commits

The simplest approach to release new app versions, is to register the app once and then push new releases by creating tagged commits on a specific branch, e.g., the main branch, or `*` to get tags from all branches.

my-app1:
  releases:
    - "git+https://github.com/aiidalab/aiidalab-my-app@main:"
my-app2:
  releases:
    - "git+https://github.com/aiidalab/aiidalab-my-app@*:v1.0.0.."

where you replace the URL shown here with the one applicable for your app.

Hint

You can use the standard git revision selection syntax to further reduce the selected commits on a release line. For example, @main:v1.0.0.. means “select all tagged commits on the main branch after commit tagged with v1.0.0”. See the “Other” tab for details and more examples.

Release specific tagged commits

Instead of automatically releasing every tagged commit, you can also specify dedicated commmits instead.

my-app:
  releases:
  - "git+https://github.com/aiidalab/aiidalab-my-app.git@v2"
  - "git+https://github.com/aiidalab/aiidalab-my-app.git@v1"

Use this approach if you want more control over which versions of your app are installable through the app store.

Other

The formal definition of the release URL is:

release-url  ::=  app-repository-url + [ "@" ( release | release-line ) ]
release      ::=  ( git-tag | git-commit-sha )
release-line ::=  branch + ":" + [ revision-selection ]

where the app-repository-url should point to a git repository and use the URL scheme git+https://. The optional revision-selection follows the standard git revision selection syntax and can be used to specify a tag range and thus, e.g., exclude early tagged commits, as opposed to releasing all tagged commits.

6: As opposed to an approach where users push new releases to the registry.

Review your app on the app store!

Once submmited, your pull request will be reviewed by the AiiDAlab registry maintainers. After it is accepted and merged it typically takes 15-30 minutes for your app (and new releases) to appear in the AiiDAlab app store.

You can also test whether your app is listed on the registry by either opening the app store in AiiDAlab or running the following command:

$ aiidalab search my-app

and install it with

$ aiidalab install my-app

Publish your AiiDAlab app#