Checklist: new release

Overview

MITE follows a rolling release cycle, with approximately monthly releases (depending on the number of submission and review speed). Releases are created by one of the maintainers, who merge new and modified existing MITE entries into the main branch. Only entries that have been reviewed and have passed the automated validation checks are eligible to be included in the next release.

Background

While MITE entries can be inspected and interacted with via the MITE Website, they are primarily managed via their GitHub repository. This repository provides version control, validation functionality, and an uninterrupted audit trail.

MITE follows the Git branching model, meaning that the "ground truth dataset" lives in the main branch (see Fig. 1A). New entries and modifications to existing entries can only be created via a pull request (PR) into the main branch (Fig 1B), and need to undergo review and automated validation checks. This allows for a high level of control about what is being added to the "ground truth dataset", which is prerequisite for a gold-standard database which MITE aims to be.

Importantly, this branching workflow is run automatically in the background whenever a user contributes to MITE via the MITE Website or a reviewer performs an entry. This design guides best practices without requiring participants to be aware of these principles. The only participants that need to be aware of the full workflow are the maintainers of the repository.

Fig. 1: MITE follows the Git branching model. A) for each new or modified existing entry, a feature branch is branched out of the main branch. B) entries undergo review by MITE reviewers. C) Only if an entry is approved and passes all validation checks, the feature branch can be merged back into the main branch. The feature branch is deleted and the entry now resides in the canonical dataset.

Pull request status

There are four types of pull request statuses:

• Draft PRs: these stubs represent incomplete user submissions. Any draft PRs older than 10 days can be safely discarded (closed and branches deleted)

• Regular PRs: these represent complete user submissions before review. Their automated tests have not yet passed (indicated by ❌). You can view the CI/CD log to get information why their status has not yet passed, as described below.

• Reviewed but failing PRs: these represent reviewed user submissions where tests still fail (indicated by ❌). You can view the CI/CD log to get information why their status has not yet passed, as described below.

• Reviewed and passing PRs: these represent reviewed user submissions passing all tests (indicated by ✔)

CI/CD Status

CI/CD run via GitHub Actions can tell you more about reasons for failure. For that, you need to inspect the respective run.

• Click the ❌ symbol and click on Details

• A new window will open and the logs will be visible, where the reason for failure is described. In this case, the entry has not been reviewed yet and is still pending. Additionally, a temporary file used for the review process is still present that does not follow the file naming convention. Both these errors will be fixed automatically once the entry is reviewed.

• In another (cnostructed) case, the UniProt ID has been malformed. This example can be fixed by providing the correct UniProt ID.

How to create a new release

Nota bene: this step-by-step guide assumes that you have maintainer rights in the mite_data repository and can merge entries. Also, all releases have to be first discussed and coordinated with the MITE coordinators.

1) Inspect the open PRs (=pending entries).

All passing reviewed entries can be merged. For all failing reviewed entries, check the logs for the reasons, and try to fix it. You can edit files in place using the GitHub GUI.

For new entries, you have to assign a new MITE ID. This should be the next-higher number (e.g. if the last MITE ID was 'MITE0000262', the new one should be 'MITE0000263'). Take care to not use any reserved accessions.

2) Merge entries into main

Once entries are reviewed and passing, merge them to main one by one, using the GitHub GUI.

This will automatically trigger the updating of the data artifacts in mite_data (derived from other data). You can inspect the status via the Actions tab. Again, if there are errors popping up (which they usually should not), inspect and take appropriate measures.

3) Manually trigger the release validation workflow

Once all entries are merged to main, go to the Actions tab and select the Prepare release workflow.

On the right-hand side, click the button Run workflow. Be aware that this workflow is time-expensive and may take a few minutes to run.

4) Prepare the release

Only if the workflow has successfully passed, you can start preparing the release. Modify the following files (e.g. using the GitHub GUI)

• pyproject.toml: update the version (only minor; e.g. 1.x)
• CHANGELOG.md: update the changelog and describe the new release

Then, you can create a new Release via the GitHub GUI. See also the README for further details.

4) Finishing

Once the release is prepared, it is automatically grabbed and archived by Zenodo. Go check if the release has been synced (if not, there is likely an issue with the metadata - investigate). To complete the release, you have to also update another repository, mite_web_extras. See the respective Wiki for next steps

Troubleshooting

1. The automated artifact updates have caused a merge conflict! How can I fix that? This happens when an entry PR was manually merged and the automatically created artifacts were not successfully merged by the GitHub Bot before another entry PR was (manually) merged. In this case, the conflicting PR must be closed, and the artifacts must be manually generated locally.

Nota bene: the following instructions assume that you have a working development installation of mite_data

TBA