diff --git a/docs/source/addingakit.rst b/docs/source/addingakit.rst index 15e1fef6..f550debb 100644 --- a/docs/source/addingakit.rst +++ b/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 diff --git a/docs/source/img/finding-ci-error.gif b/docs/source/img/finding-ci-error.gif new file mode 100755 index 00000000..745acdcc Binary files /dev/null and b/docs/source/img/finding-ci-error.gif differ diff --git a/docs/source/maintaining_a_kit/improving.rst b/docs/source/maintaining_a_kit/improving.rst new file mode 100644 index 00000000..eac401df --- /dev/null +++ b/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 `: get recognition for your code! + +You could even opt to :ref:`add a logo ` to add unique flair to your MDAKit! + + +.. note:: + + If applicable, remember to :ref:`update your kit's metadata ` + so changes and additions are reflected on the Registry. + + +.. toctree:: + :maxdepth: 1 + :caption: Index + + publishing + logo diff --git a/docs/source/maintaining_a_kit/keep-healthy.rst b/docs/source/maintaining_a_kit/keep-healthy.rst new file mode 100644 index 00000000..2df1d10f --- /dev/null +++ b/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 ` 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 `_, +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 `_ 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 `_. + +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 ` 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 ` 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 `_ +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 ` +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 `_ 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 diff --git a/docs/source/maintaining_a_kit/logo.rst b/docs/source/maintaining_a_kit/logo.rst new file mode 100644 index 00000000..c1361eb3 --- /dev/null +++ b/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 + diff --git a/docs/source/maintaining_a_kit/publishing.rst b/docs/source/maintaining_a_kit/publishing.rst new file mode 100644 index 00000000..47158a92 --- /dev/null +++ b/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 `_. JOSS papers are short and +`relatively simple _ - +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 `_. If you log in to Zenodo using your GitHub +account, you can easily do this from the +`Zenodo GitHub page `_. + diff --git a/docs/source/maintaining_a_kit/updatemetadata.rst b/docs/source/maintaining_a_kit/updatemetadata.rst new file mode 100644 index 00000000..a793480a --- /dev/null +++ b/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 ` 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. + + diff --git a/docs/source/maintainingakit.rst b/docs/source/maintainingakit.rst index 6836daa1..ebd7d001 100644 --- a/docs/source/maintainingakit.rst +++ b/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 `: +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 `! diff --git a/docs/source/making-a-kit/documentation.rst b/docs/source/making_a_kit/documentation.rst similarity index 100% rename from docs/source/making-a-kit/documentation.rst rename to docs/source/making_a_kit/documentation.rst diff --git a/docs/source/making-a-kit/from-cookiecutter.rst b/docs/source/making_a_kit/from-cookiecutter.rst similarity index 86% rename from docs/source/making-a-kit/from-cookiecutter.rst rename to docs/source/making_a_kit/from-cookiecutter.rst index 8d08ad67..f6760a53 100644 --- a/docs/source/making-a-kit/from-cookiecutter.rst +++ b/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 diff --git a/docs/source/making-a-kit/guided-example/add-code.rst b/docs/source/making_a_kit/guided_example/add-code.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/add-code.rst rename to docs/source/making_a_kit/guided_example/add-code.rst diff --git a/docs/source/making-a-kit/guided-example/add-docs.rst b/docs/source/making_a_kit/guided_example/add-docs.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/add-docs.rst rename to docs/source/making_a_kit/guided_example/add-docs.rst diff --git a/docs/source/making-a-kit/guided-example/add-tests.rst b/docs/source/making_a_kit/guided_example/add-tests.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/add-tests.rst rename to docs/source/making_a_kit/guided_example/add-tests.rst diff --git a/docs/source/making-a-kit/guided-example/make-release.rst b/docs/source/making_a_kit/guided_example/make-release.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/make-release.rst rename to docs/source/making_a_kit/guided_example/make-release.rst diff --git a/docs/source/making-a-kit/guided-example/registering.rst b/docs/source/making_a_kit/guided_example/registering.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/registering.rst rename to docs/source/making_a_kit/guided_example/registering.rst diff --git a/docs/source/making-a-kit/guided-example/to-github.rst b/docs/source/making_a_kit/guided_example/to-github.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/to-github.rst rename to docs/source/making_a_kit/guided_example/to-github.rst diff --git a/docs/source/making-a-kit/guided-example/use-cookiecutter.rst b/docs/source/making_a_kit/guided_example/use-cookiecutter.rst similarity index 100% rename from docs/source/making-a-kit/guided-example/use-cookiecutter.rst rename to docs/source/making_a_kit/guided_example/use-cookiecutter.rst diff --git a/docs/source/making-a-kit/hosting.rst b/docs/source/making_a_kit/hosting.rst similarity index 100% rename from docs/source/making-a-kit/hosting.rst rename to docs/source/making_a_kit/hosting.rst diff --git a/docs/source/making-a-kit/license.rst b/docs/source/making_a_kit/license.rst similarity index 100% rename from docs/source/making-a-kit/license.rst rename to docs/source/making_a_kit/license.rst diff --git a/docs/source/making-a-kit/testing.rst b/docs/source/making_a_kit/testing.rst similarity index 100% rename from docs/source/making-a-kit/testing.rst rename to docs/source/making_a_kit/testing.rst diff --git a/docs/source/makingakit.rst b/docs/source/makingakit.rst index 8cdc4caf..7ab31cfe 100644 --- a/docs/source/makingakit.rst +++ b/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 diff --git a/docs/source/registering-a-kit/metadata-yaml.rst b/docs/source/registering_a_kit/metadata-yaml.rst similarity index 100% rename from docs/source/registering-a-kit/metadata-yaml.rst rename to docs/source/registering_a_kit/metadata-yaml.rst diff --git a/docs/source/registering-a-kit/step-by-step.rst b/docs/source/registering_a_kit/step-by-step.rst similarity index 100% rename from docs/source/registering-a-kit/step-by-step.rst rename to docs/source/registering_a_kit/step-by-step.rst