The `metadata.yaml` file

The metadata.yaml file is a YAML format file containing important information about an MDAKit. A template can be found below and in the MDAKit repository (mdakits/template/metadata.yaml). For an example of a completed metadata.yaml, see the guided example.

The file includes both required and optional entries:

Required entries: Any variable in the ‘required entries’ section must be provided. If missing or empty, the MDAKit cannot be registered.
Optional entries: Any variable in the ‘optional entries’ section may be left empty or be left out. However, it is recommended to provide as much information as possible. Some aspects of the registry checks may not work if these details are missing.

Please see the comments in the template for an explanation of all possible items. Some additional notes on specifying how to run tests are also provided below.

Note

For now, the template file serves as the primary specification for the MDAKits registry metadata.yaml file. The MDAKits registry specification will likely be updated in the future with new optional and required entries. The MDAKits team will assist developers with migrations should they become necessary.

Template `metadata.yaml` file

Start from this template (also available at mdakits/template/metadata.yaml) when creating a metadata.yaml for your MDAKit. See the comments for an explanation of each item, and replace the values as appropriate for your MDAKit, noting the sections for required entries and optional entries.

The template uses the strings GH_HOST_ACCOUNT, MYPROJECT, and MYPACKAGE to indicate that you should be filling in your details!

GH_ACCOUNT: The GitHub account where the source code repository is held; typically your username or the organization that you’re part of.
MYPROJECT: The name of your project. This is the name of your repository. In the template we also use it as the PyPi/conda package name.
MYPACKAGE: The name of the Python package. It describes how you import it in Python code, i.e. it is used in import MYPACKAGE.

Note on YAML format: Please look at the YAML format specifications to learn more about how to write correct YAML files. Note that YAML is a file format where indentation matters so make sure that your editor uses spaces and not TAB for indentation, as this can lead to incorrect YAML. Lines starting with hash marks # are comments. You can add your own comments and modify the existing ones as needed.

# TEMPLATE MDAKit file
# --------------------
#
#------------------------------------------------------------
# Required entries
#------------------------------------------------------------
## str: name of the project (the respository name)
project_name: MYPROJECT

## List(str): a link to the authors file (preferred) or a list of authors 
authors:
  - https://github.com/GH_HOST_ACCOUNT/MYPROJECT/blob/main/AUTHORS.md

## List(str): a list of maintainers
## Please note these _must_ be GitHub handles
## The maintainers will be tagged in issues if their MDAKit is failing.
maintainers:
  - NAME1
  - OPTIONAL_NAME2
  - OPTIONAL_NAME3

## str: a free form description of the mdakit
description:
    (REPLACE WITH A SHORT DESCRIPTION OF WHAT YOUR MDAKit DOES.)

## List(str): a list of keywords which describe the mdakit
keywords:
  - KEYWORD1
  - KEYWORD2

## str: the license the mdakit falls under
## See https://spdx.org/licenses/ for valid license specifiers
license: GPL-2.0-or-later

## str: the link to the project's code
## Please note that this is not limited to GitHub! Can be Gitlab, etc..
project_home: https://github.com/GH_HOST_ACCOUNT/MYPROJECT/

## str: the link to the project's documentation
documentation_home: https://MYPROJECT.readthedocs.io

## str: the type of documentation available [UserGuide, API, README]
documentation_type: UserGuide + API

## List(str): a list of commands to use when installing the mdakit from its
## source code.
src_install:
  - pip install git+https://github.com/GH_HOST_ACCOUNT/MYPROJECT@main

## str: the package name used to import the mdakit
import_name: MYPACKAGE

## str: a specification for the range of Python versions supported by this MDAKit
python_requires: ">=3.10"

## str: a specification for the range of MDAnalysis versions supported by this MDAKit
mdanalysis_requires: ">=2.0.0"

## List(str): a list of commands to use when attempting to run the MDAKit's tests
## If you package your tests inside your package then you can typically use the 
##     pytest --pyargs MYPACKAGE
## command as shown below. 
## Otherwise you need to include commands to make the tests available. 
## For example, if the tests are in the repository at the top level under `./tests`:
## First use `git clone latest` to either clone the top commit for "development code" checks or check out
## the latest tag for "latest release" checks. Then then run pytest:
##    - git clone latest
##    - pytest -v ./tests
## Feel free to ask for advice on your pull request!
run_tests:
  - pytest --pyargs MYPACKAGE

## List(str): a list of commands to use to install the necessary dependencies required
## to run the MDAKit's tests.
## The default below _might_ be sufficient or you might not even need MDAnalysisTests:
## make sure that it is appropriate for how you run tests.
test_dependencies:
  - mamba install pytest MDAnalysisTests

## str: the organisation name the MDAKit falls under
project_org: GH_HOST_ACCOUNT

#------------------------------------------------------------
# Optional entries
#------------------------------------------------------------   
## List(str): a list of commands to use when installing the latest
## release of the code. Note: only one installation method can currently
## be defined. We suggest using mamba where possible (e.g.
##   mamba -c conda-forge install MYPROJECT
## for a conda package installation).
## Here we use a simple PyPi installation:
install:
  - pip install MYPROJECT

## str: the development status of the MDAKit
## See https://pypi.org/classifiers/ for development status classifiers.
development_status: Production/Stable

## List(str) a list of publications to cite when using the MDAKit
## Links to scientific publications or stable URLs (typically of the form
## https://doi.org/<DOI> or to a preprint server)
publications:
  - URL1
  - URL2

## str: a link to the MDAKit's community (mailing list, github discussions, etc...)
community_home: URL

## str: a link to the MDAKit's changelog
changelog: https://github.com/MYNAME/MYPROJECT/blob/main/CHANGELOG.md

Specifying tests

The commands for running your MDAKit’s tests must be added under the run_tests entry. Assuming that your tests are in a test/ directory at the top level of your repository, you could define your test commands as:

run_tests:
  - git clone latest
  - pytest -v tests/

This makes a clone of your repository based on your latest release tag on GitHub and navigates into the repository root. Note that this is not a true git command, but is instead specific to the MDAKits registry workflow and depends on the project_home field in the metadata.yaml file.

The pytest command then runs the tests found inside the tests/ directory. If your tests are elsewhere, change this path appropriately.

Dependencies that are only required for testing are indicated in the test_dependencies object. Suppose your package uses pytest, and used the MDAnalysisTests for sample data. This is reflected in your MDAKit metadata with:

test_dependencies:
  - mamba install pytest MDAnalysis

The metadata.yaml file

Template metadata.yaml file

Specifying tests

The `metadata.yaml` file

Template `metadata.yaml` file