Expand the "Maintaining an MDAKit" documentation

docs/source/addingakit.rst

@@ -21,8 +21,8 @@ about this process and more detail about the ``metadata.yaml`` file.
 .. toctree::
    :maxdepth: 2
 
-   registering-a-kit/step-by-step
-   registering-a-kit/metadata-yaml
+   registering_a_kit/step-by-step
+   registering_a_kit/metadata-yaml
 
 
 .. _`MDAKit registry`: https://mdakits.mdanalysis.org/mdakits.html

docs/source/maintaining_a_kit/improving.rst

@@ -0,0 +1,49 @@
+#####################
+Improving your MDAKit
+#####################
+
+Adding new features
+===================
+Developing your MDAKit can involve, for example, adding new features, or 
+altering existing ones to improve performance or user-friendliness. This may 
+come at your own initiative, or the request of a user.
+
+How you develop your kit is up to you! Just remember it's a good idea to  
+develop the tests and documentation alongside the new code (and to run the 
+existing tests to ensure you aren't causing any unintended changes).
+
+
+Go beyond the minimal MDAKit Registry requirements
+==================================================
+The requirements for registering an MDAKit are intentionally minimal to keep 
+the entry barrier low. **Going beyond these minimal requirements is highly
+recommended**.
+
+This may include (but is not limited to):
+
+- **More tests**: can you get to 100% coverage?!
+- **More documentation**: Explain each part of your code. Add examples. Make
+  your documentation visually appealing and easy to navigate!
+- **Use tooling and workflows**: set up and personalise automatic features to
+  check code formatting, run your own automated testing (don't rely solely on 
+  the MDAKit Registry's CI!), automatically publish new releases, and more!
+- **Community resources**: make it easy for users to report issues, ask 
+  questions - or even contribute to your MDAKit themselves!
+- **Release on PyPi/conda-forge**: make it easier for users to install your kit! 
+- :ref:`Make a journal publication <publishing>`: get recognition for your code!
+
+You could even opt to :ref:`add a logo <logo>` to add unique flair to your MDAKit!
+
+
+.. note::
+
+    If applicable, remember to :ref:`update your kit's metadata <update-metadata>` 
+    so changes and additions are reflected on the Registry.
+
+
+.. toctree::
+   :maxdepth: 1
+   :caption: Index
+
+   publishing
+   logo

docs/source/maintaining_a_kit/keep-healthy.rst

@@ -0,0 +1,164 @@
+*************************
+Keeping an MDAKit healthy
+*************************
+
+
+The MDAKit Registry CI
+######################
+
+
+.. _mdakitsci:
+
+What is the 'MDAKit Registry CI'?
+---------------------------------
+
+The MDAKit Registry Continuous Integration is run twice a week and involves the 
+(automatic) running of each kit's tests (as specified in the ``metadata.yaml`` 
+file.
+
+If the tests **pass**, the kit's 'CI badges', which appear on the 
+:ref:`Registry <mdakits>` and are visibile to all potential users, remain green.
+
+If the tests **fail**, an issue is automatically raised on the 
+`MDAKits Registry GitHub issue tracker <https://github.com/MDAnalysis/MDAKits/issues>`_, 
+the maintainers (as identified in 
+``metadata.yaml``) are notified, and the CI badges updated to red to inform
+others.
+
+Note that there are two CI runs:
+
+- **develop**, using the 'source' version (assumed to be the development 
+  version) of your MDAKit (i.e., what is installed when running the commands 
+  under ``src_install`` in ``metadata.yaml``), and the current ``develop`` 
+  (under active development) branch of MDAnalysis.
+
+- **latest**, (if applicable) using the latest release of your MDAKit (installed
+  when running the commands under ``install`` in ``metadata.yaml``), and the 
+  most recent release of MDAnalysis.
+
+Depending on the nature of the failure, one or both of *develop* and 
+*latest* may be failing. In many cases it will be only *develop* failing, as the 
+effects of new changes to your kit (or to MDAnalysis) will be seen here as they
+are made, but only in *latest* after the changes are published in a new release. 
+Having *develop* gives you a chance to find and fix errors before they are 
+carried through to a release, avoiding impacting (most) users.
+
+
+.. _failingci:
+
+Why did CI fail?
+----------------
+There are a number of reasons that the CI tests may fail - it could be an
+internal issue arising as you develop your kit, or it may indicate that updates
+are needed to keep in line with changes within MDAnalysis or other dependencies.
+It may reflect a single test that is no longer passing, or that a larger error
+is preventing your kit from being installed/any tests from being run.
+
+You may already know the likely source of your kit's failure. If you have your own
+CI, this could be a place to start.
+
+Otherwise, you can read the CI log file for the MDAKit Registry CI run to find the 
+exact point of failure and accompanying error messages:
+
+#. Click on the `Actions tab <https://github.com/MDAnalysis/MDAKits/actions>`_ on 
+   the MDAKits Github page.
+
+#. Click on the most recent *'GH Actions Cron CI'* job.
+
+#. Under *'Annotations'*, find and click the failing job(s) with your kit's 
+   name. Failing jobs should show a red cross and be grouped at the top.
+
+#. You should be directed to the place in the CI log where the failure occurs.
+   Some scrolling may be required to find the origin of the error.
+
+.. image:: ../img/finding-ci-error.gif
+   :alt: Finding the error message after being notified of a failing CI run
+
+
+Fixing an failure
+-----------------
+Once the point of failure has been identified, you can set about trying to fix
+it. The exact fix required will of course depend on exactly what went wrong, but
+hopefully the error message(s) in the log will be enough to get you started. If
+you believe the issue is due to a breaking behaviour change in MDAnalysis, we
+encourage you to raise an issue on the 
+`core library issue tracker <https://github.com/MDAnalysis/mdanalysis/issues>`_.
+
+Any fixes will be applied in your kit's home repository - no direct interaction
+with the Registry is required.
+
+If you're still not sure what's gone wrong or how to fix it, you can comment on 
+the issue that was raised on the `MDAKits GitHub`_. The MDAKits team, or
+other members of the community, may be able to help - but remember, ultimate
+responsibility remains with **you**. 
+
+.. note::
+
+   If your fix affects any your kit's metadata.yaml, e.g. if the installation
+   instructions changed, rember to 
+   :ref:`update your metadata <update-metadata>` as appropriate.
+
+
+After applying a fix
+--------------------
+Once you have applied a fix to your MDAKit (and, if applicable, pushed a new 
+release with these changes applied), no further action is required from you.
+
+Assuming that the fix does indeed solve the issue, the tests will pass the next
+time the automated CI is run. After the successful run, the CI badges on the
+:ref:`Registry <mdakits>` will be restored to 'passing' and the issue raised on
+the `MDAKits GitHub`_ will be automatically closed.
+
+
+Keeping an eye out for upstream changes
+=======================================
+Avoid failing tests before they happen!
+
+Just as you are likely to keep improving your kit, the upstream packages on
+which it relies - including MDAnalysis - will also continue to evolve. 
+Sometimes, this means that the parts of your kit that rely on these packages 
+will no longer work. 
+Keeping an eye out for such changes will allow you to modify your kit 
+appropriately *before* the upstream change is fully applied and your code 
+starts to fail.
+
+Usually, a package will warn users of any upcoming changes that may affect
+downstream usage (e.g. changing how a function is to be used), by raising
+a `DeprecationWarning <https://docs.python.org/3/library/exceptions.html#DeprecationWarning>`_
+indicating the upcoming change when used. 
+If your kit relies on any such to-be-changed features, these warnings will
+be triggered when accessing the deprecated feature, and (assuming the relevant
+core is covered by your kit's tests) will appear in the output logs, so it's a
+good idea to keep an eye on these.
+
+Testing against *development* versions of packages, not just the latest release,
+can also allow you to catch issues early. The :ref:`MDAKits Registry CI <mdakitsci>` 
+tests both the latest release and development versions of your kit and MDAnalysis. 
+If you've used the MDAKits cookiecutter, the generated GitHub workflow tests with
+both the development and latest release of MDAnalysis.
+
+It is also a good idea check release notes for new releases of packages your kit
+uses and watch for any announcements of major upcoming changes.
+
+
+Keeping support windows in mind
+===============================
+Your kit should specify which versions of the software it relies on (including
+Python) it works with. Ideally, as new versions of these dependencies are 
+released, your kit will be updated to work with these. 
+
+It is *not* expected that your kit remains compatible with *all* historic 
+releases - and indeed, many old versions of these packages will not work with
+each other. These packages will also have **support windows** of how long after
+a given release the developers will keep an eye to make sure it still works as 
+intended.
+
+`SPEC0 <https://scientific-python.org/specs/spec-0000/>`_ is a standard outlining 
+a timeline of which versions of Python and common dependencies in the Scientific
+Python ecosystem should minimally aim to be supported and compatible with each other. You can
+follow SPEC0 to determine which Python/dependency versions you should aim to
+support, and which old versions you can drop.
+
+
+.. _`MDAKits GitHub`:
+   https://github.com/MDAnalysis/MDAKits/issues

docs/source/maintaining_a_kit/logo.rst

@@ -0,0 +1,28 @@
+.. _logo:
+
+Adding a logo for your MDAKit
+=============================
+A custom logo can add some pizazz to your MDAKit. You are welcome to create an
+entirely custom logo, use the default `'empty gear' template`_, 
+or modify the template - feel free to place your logo within the gears!
+
+If you used the MDAKits cookiecutter, there is already a placeholder logo in 
+your documentation. The `MDAKits cookiecutter documentation`_ has information 
+on updating this.
+
+.. note::
+   MDAnalysis recommends that kit authors carefully check that any material used 
+   in their kit - including logos - is used under appropriate licenses, and do
+   not infringe on any copyrights. 
+
+   MDAnalysis cannot give any legal advice on these matters; if you are unsure 
+   about any legal matters, please consult a lawyer.
+
+
+.. _`MDAKits cookiecutter documentation`:
+   https://cookiecutter-mdakit.readthedocs.io/en/latest/usage.html#documentation-configuration
+
+
+.. _`'empty gear' template`:
+   https://github.com/MDAnalysis/branding/tree/main/templates/MDAKits
+

docs/source/maintaining_a_kit/publishing.rst

@@ -0,0 +1,21 @@
+.. _publishing:
+
+Publishing your MDAKit!
+=======================
+Providing a way to easily cite your MDAKit - e.g by having an associated DOI -
+can make it easier for users to share your code and for you to get recognition
+when someone uses your work.
+
+Ideally, you could publish an article about your kit in a journal such as 
+`JOSS <https://joss.readthedocs.io/>`_. JOSS papers are short and
+`relatively simple <https://joss.readthedocs.io/en/latest/submitting.html#submission-process`>_ -
+In meeting the requirements for registering an MDAKit, you will have already
+met many of the JOSS submission requirements. Once you've built up your kit's
+documentation and testing, consider publication with JOSS or a similar journal!
+
+If you don't have a publication to directly associated with your MDAKit, we 
+recommend at least generating a DOI for your code repository, e.g through 
+`Zenodo <https://zenodo.org/>`_. If you log in to Zenodo using your GitHub 
+account, you can easily do this from the 
+`Zenodo GitHub page <https://zenodo.org/account/settings/github/>`_.
+

docs/source/maintaining_a_kit/updatemetadata.rst

@@ -0,0 +1,18 @@
+.. _update-metadata:
+
+Updating the MDAKit's metadata
+==============================
+As your kit evolves, you may find the information you supplied in the 
+:ref:`metadata <specification>` file at registration is no longer valid (e.g.
+the installation instructions mught require updating), or wish to otherwise
+alter or add new details (e.g. adding a publication, or expanding the 
+description).
+
+**If you don't update your metadata, potential users could be getting the wrong
+information, and/or the automated tests run by the MDAKit Registry could fail.**
+
+To update your kit's metadata, simply edit the kit's ``metadata.yaml`` (in your
+fork of the ``MDAKits`` repository), then make a new Pull Request (PR). The 
+MDAKits team will then review and merge your PR to apply the changes.
+
+

docs/source/maintainingakit.rst

@@ -9,19 +9,42 @@ Maintaining an MDAKit
    like to see covered here, please get in touch via 
    `MDAnalysis Github Discussions`_.
 
-There are a variety of reasons a kit may behave unexpectedly after being 
-submitted to the registry. Apart from actively developing the kit, changes in 
-kit dependencies, or even Python itself, can introduce/deprecate new/old functionality.
-For this reason, the kits' continuous integration is rerun weekly to 
-confirm the kits expected behavior.
-
-In the event that a kit no longer passes its tests, an issue in 
-MDAnalysis/MDAKits is automatically raised while notifying the maintainers 
-indicated in the `metadata.yaml` file.
-While the registry developers will be happy to help where possible, ultimately,
-the maintainers of the MDAKit are responsible for resolving such issues and 
-ensuring that the tests pass.
-The issue will automatically close after the next CI run if the tests pass again.
+Successfully registering an MDAKit is not the end of the journey! A
+software package still requires input to keep it healthy and thriving. 
+This includes both expanding and adding new features and ensuring the MDAKit 
+continues to run as intended. **While not required for an MDAKit to remain in
+the registry, such activities are highly encouraged**. 
+
+
+Now that it is registered, your kit will be part of the :ref:`MDAKits Registry CI <mdakitsci>`:
+your kits' tests (as specified in ``metadata.yaml``) are automatically rerun 
+twice each week, so that you (and potential users) have assurance that your 
+code still works as intended, or are notified when it does not. 
+
+**However, the ultimate responsibility for maintaining your MDAKit remains with
+you.**
+
+
+The sections below provide some information to keep in mind for maintaining your
+MDAKit after registration.
+
+
+.. toctree::
+   :maxdepth: 1
+
+   maintaining_a_kit/keep-healthy
+   maintaining_a_kit/updatemetadata
+
+.. toctree::
+   :maxdepth: 2
+
+   maintaining_a_kit/improving
+
+
 
 .. _`MDAnalysis GitHub Discussions`:
    https://github.com/MDAnalysis/mdanalysis/discussions
+
+
+Want to go even further beyond your MDAKit? You can also help us out by 
+:ref:`reviewing other MDAKits <reviewers-guide>`! 

docs/source/making-a-kit/from-cookiecutter.rst → docs/source/making_a_kit/from-cookiecutter.rst

@@ -1,4 +1,4 @@
-.. _guided-example:
+.. _guided_example:
 
 *********************************************
 Guided Example: Building an RMSF analysis Kit
@@ -41,11 +41,11 @@ requirements!
    :maxdepth: 1
    :caption: Steps for creating an MDAKit from the cookiecutter
 
-   guided-example/use-cookiecutter
-   guided-example/add-code
-   guided-example/add-tests
-   guided-example/to-github
-   guided-example/add-docs
-   guided-example/make-release
-   guided-example/registering
+   guided_example/use-cookiecutter
+   guided_example/add-code
+   guided_example/add-tests
+   guided_example/to-github
+   guided_example/add-docs
+   guided_example/make-release
+   guided_example/registering
 

docs/source/makingakit.rst

@@ -20,7 +20,7 @@ to registration, is provided below.
 .. toctree::
    :maxdepth: 2
 
-   making-a-kit/from-cookiecutter
+   making_a_kit/from-cookiecutter
 
 
 Building without the cookiecutter (or from an existing project)
@@ -38,7 +38,7 @@ information below.
 .. toctree::
    :maxdepth: 1
 
-   making-a-kit/license
-   making-a-kit/hosting
-   making-a-kit/testing
-   making-a-kit/documentation
+   making_a_kit/license
+   making_a_kit/hosting
+   making_a_kit/testing
+   making_a_kit/documentation