diff --git a/docs/source/index.rst b/docs/source/index.rst index 517aa181..242bfa99 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -9,18 +9,31 @@ MDAnalysis Toolkits (MDAKits) Welcome to the MDAKit registry! Showcased here are a list of community generated packages which extend the -functionality of the `MDAnalysis library`_ +functionality of the `MDAnalysis library`_. +Follow the links below to begin exploring the available MDAKits, or view +additional resources about MDAKits and how to write and/or add your own. + +Take me to the `MDAKit Registry`_! +================================== .. toctree:: :maxdepth: 1 - :caption: Table of Contents + :hidden: + :caption: MDAKit Registry mdakits + + +.. toctree:: + :maxdepth: 1 + :caption: Resources + about makingakit add troubleshooting + reviewersguide Acknowledgements @@ -29,6 +42,7 @@ The development of this repository is supported by a grant from the Chan Zuckerb Initiative under an EOSS4 award. +.. _`MDAKit registry`: https://mdakits.mdanalysis.org/mdakits.html .. _`MDAnalysis library`: https://docs.mdanalysis.org diff --git a/docs/source/reviewersguide.rst b/docs/source/reviewersguide.rst new file mode 100644 index 00000000..2d2d085c --- /dev/null +++ b/docs/source/reviewersguide.rst @@ -0,0 +1,267 @@ +******************* +Guide for reviewers +******************* + +The MDAKit registration process aims to present a *low barrier of entry* for contributors to make their +code available to the broader community via the `MDAKit registry`_. +However, there is still a minimal set of :ref:`requirements ` that must be met, and the +MDAKit must pass a review before it is officially included in the Registry. + +A manual review also allows for more experienced reviewers to offer best-practice suggestions and +improvements to newer contributors. As such, your **aims as a reviewer** are to: + +#. Ensure the MDAKit can be *merged* (all necessary details *present* and *correct*), and +#. Encourage *best practices* and *future work*. + + +This page provides a guide for reviewing an MDAKit submission, including a brief overview of the +registration process and: + +* what **AUTOMATIC** checks are performed, +* what to **CHECK** manually (things that must be present before the kit can be registered), and +* things to **RECOMMEND** (suggestions for improving the provided metadata, but that are not required). +You can also see the :ref:`guide for submitters here`. + +.. note:: + The `MDAKit registry`_ is still evolving. This guide will be updated as changes to the registration + process are made. + +Who can be a reviewer? +====================== +We love for members of the community to get involved at all parts of the MDAKit process! Contact us if +you’d like to be involved with reviewing MDAKit submissions. + +How does registration work? +=========================== +A prospective MDAKit contributor will register their Kit by creating a Pull Request (PR) to the MDAKit +github repository, consisting of a single `metadata.yaml` file (or one per Kit, if multiple Kits are +being added/modified). Details on what is included in the metadata file, and what to look for as a +reviewer, are provided :ref:`below `. + +Several checks will run automatically: + +- *gen_matrix* generates a list of all MDAKits updated by the PR (usually, this will be a single Kit) +- *mdakit-ci* will install the MDAKit and run its own tests (as detailed in + the `metadata.yaml` file) with the latest and/or develop versions of MDAnalysis +- *readthedocs* will create a version of the MDAKit Registry website with the prospective kit added + +Once the kit has passed both these automatic checks **and** the manual checks below, you can approve the +PR - after merging, the Kit will officially be part of the MDAKit Registry! + +What to look for as a reviewer +============================== + +On the PR +********* + +- **CHECK**: Are the automatic checks all passing? + + - You many need to manually start the checks if the contributor is new to the organisation + - If the Kits’ tests use `tox`, these need to be manually checked (follow the *Details* link), + as they may incorrectly appear to pass. + + If checks are failing, you may need to help the contributor identify and fix the issue. A failure may + be due to improper set up of `metadata.yaml` (see :ref:`below `), or a local failure on + the MDAKit’s end. Follow the *Details* of the failed check to find out more. + + Some other possible points of failure: + + - If the failure has a “The head commit for this pull_request event is not ahead of the base + commit” error, tell the contributor to update the branch used in the PR so it is up-to-date + with *main* (e.g. using `git rebase`) + - A failure on installing dependencies may be due the entires in the Kit’s `pyproject.toml` not + being properly defined + + +- **CHECK**: Did the docs build correctly? + + View the page generated by `readthedocs` (by clicking *Details* next to the check) and find the + MDAKit’s entry on the Registry page. Check the expected information and badges are present on both the + main list and the Kit’s individual page. + + +- **CHECK**: Is the metadata file named correctly and in the right location? + + The correct format is: `mdakits//metadata.yaml` (see `project_name`, below) + + +At the MDAKit’s Project Home +***************************** +Follow the link to the project’s home provided in the metadata file and have a quick look at the MDAKit +to see if it looks sensible. Much of the information provided in the metadata file should also be +available here (e.g. a LICENCE file containing licence information, installation instructions, etc). +Check these details match the metadata information. + +| +.. _metadatafile: +Inside the metadata file +************************ + +The metadata file is in `YAML format`_. Each entry is described briefly below; see also the +:ref:`template metadata file