Guide for Maintainers

This page is a preliminary Guide for Maintainers that provides notes on package and repository management. It contains contributions from different people involved with the MDAnalysis organization and project and does not claim to be internally consistent or follow any particular policy unless noted.

Maintenance is an important but often thankless job. Please be kind to anyone who does this work.

General

Responsibility

If you're maintaining a package, be aware that many other people rely on your work, even if they don't know it. Be careful and considerate. If things go wrong (like a bad release), then do the right thing: let people know and fix the problem, be transparent.

Common tasks

Part of maintenance are the following tasks (although that's not an exhaustive list)

Daily tasks

• Monitoring the issue tracker and triaging issues (responding, pinging appropriate developers, closing)

Weekly tasks

• Check that continuous integration is passing & still running
• Implementing any bug fixes for any issues that might have been identified
• Monitoring & participating in pull requests (pinging reviewers, reviewing, merging or rejecting)

Monthly-ish tasks

• Check that the code is working up the latest upstream releases (MDAnalysis, numpy, scipy, etc..)
• Updating continuous integration components for newer actions/dependencies

Yearly tasks

• Update the code base for newer Python versions (roughly every October of every year).
• Keep up to date with NEP29 by updating dependencies.

Ad-hoc tasks

• Making releases (pypi, conda-forge) depending on changes to the code.
• Acting upon any maintenance tasks / advisories which are being communicated from the MDAnalysis core development team.

conda-forge

conda packages are essential for the Python eco-system in which MDAnalysis lives. All MDAnalysis-related conda packages are distributed via conda-forge. As a maintainer you should also acquire an understanding how to maintain conda-forge packages.

For each conda package there exists a feedstock under https://github.com/conda-forge/ and the instructions to build a conda package are called a recipe. As a recipe maintainer you are an admin of the feedstock.

The most important points are

• Creating a new conda-forge package: make a PR in https://github.com/conda-forge/staged-recipes/. This may take a while (days to weeks, depending on availability of reviewers).
• The conda-forge bot will update a feedstock when a new PyPi release appears (typically within hours or a day). You then have to review the bot's PR. Do not blindly hit "approve" and merge: you do need to check that the dependencies are correctly listed (e.g., Python versions, changed dependency versions, removed a dependency).

Deploying a release

Most packages within the MDAnalysis ecosystem have github actions implemented for automated deployment. This section highlights the release process for these packages. Should your package not have automated deployment, please get in contact with the MDAnalysis core team for guidance on implementing one.

The basic workflow for a release is as follows:

1. Make sure that you have tied off the changelog & updated any release files (these will depend on each repository).

2. From a fully updated default branch (either main or master if you are dealing with an older repository), create & push tags:

   git tag -m "release 0.7.2 of pyedr and panedr" v0.7.2
   git push --tags origin
   

3. Check the github actions for the repository and check that the TestPyPi upload checks have gone through successfully.

4. Make a release on the github page of the repository using the recently uploaded tag. Make sure to include any relevant information that you might want users to know about this release.

5. Check that the published release has triggered the github action workflow for uploading to PyPi and that it has completed successfully.

6. Once uploaded to PyPi, the conda-forge bot should automatically open up a Pull Request on the feedstock for that package (this might take a little while). Review the Pull Request, update any dependencies as necessary, and merge it.

7. Your release is now complete, go back to your package and update the changelog etc.. to start the next release cycle.

MDAKits

MDAKits are standalone packages containing code using components from the MDAnalysis library with the aim of solving specific scientific problems or in some form enhance the functionality of the MDAnalysis core library. An MDAKit can be written by anyone and hosted anywhere. We have a registry of kits at https://mdakits.mdanalysis.org and the MDAnalysis project maintains a number of MDAKits.

What does one do as a MDAKit maintainer?

Keep them alive so that users can rely on the code being available and working with the latest version of MDAnalysis. Grow them and make them thrive!

Most of what is said under Common tasks applies. Firstly, this means keeping an eye on the repo and on the registry status. If things break, investigate and raise issues. Then try to get people to fix them or fix them yourself if you can. Typically, make a release to chase the newest Python version or when something gets fixed. As a maintainer you have full control over a code repository and also associated components such as a PyPi project (for pip packages) or a conda-forge recipe (for conda packages).

Releases are automated on all of our MDAKits — you tag, then make a release in GitHub (although you should probably test the package when it is sent to test.pypi); see Deploying a release for details.

If you're new to maintenance then we'd like you to initially work with someone who's done this for a while. All current kits already have some maintainers but we really like others to join and take over!

How to become a MDAKit maintainer in the MDAnalysis org?

(@orbeckst's opinion (2023-10-31))

Talk to MDAnalysis developers in one of the public channels (mailing lists & discord). Become known in the community by helping in the discussion forums or contributing fixes as PRs (expecially for a package you're interested in!). Ultimately, handing over full control over a repository under https://github.com/MDAnalysis requires some trust so we want to get to know you.

How to create a conda-forge package for an MDAKit

Some generic information about creating a conda-forge "feedstock" was given above. To submit a new package / MDAKit to conda-forge, we suggest that you follow the steps outlined in the conda-forge documentation.

Pure Python projects

We recommend that you use the grayskull generator for an already PyPi deployed package to save you time. This is detailed in the above mentioned conda-forge documentation.

Two changes you will likely need to make to the generate meta.yaml are (note that the conda-forge linter will tell you if these are not addressed at time of submission):

1. The license choice is often incorrectly picked up. For example, grayskull may set the license to "gpl-2.0" which isn't a correct SPDX license definition.
2. The home field under about is not generated, you will need to add that with the link to the MDAKit.

Cython projects

Projects that use Cython will have more complicated builds. A specific guide on how to write these will not be written here as it tends to change often.

Here are a couple of things to take into account:

1. NumPy pinning - in order to maintain ABI compatibility, you will need to consider how to handle NumPy pinning for the repository. ABI incompatibility has been mostly fixed as of NumPy 1.25, but this has yet to filter down to conda-forge. See this page for more details.
2. Other architectures - you may need to add support for non-x86_64 architectures. These are supported by conda-forge, but you will often need to trigger the correct migration to make it happen.