Skip to content

Contributing

Midas is developed by a small team at PSI and TRIUMF, with contributions from experiments around the world. There are many ways to help: reporting problems, sharing the code you wrote for your experiment, and improving midas and its documentation.

Asking questions and reporting problems

The midas forum is the main place for questions, problem reports, requests for new features and announcements. It is an ELOG logbook. Register on the forum to be emailed when new entries are posted.

You can also report bugs on the issue tracker of the midas repository. A good report says which version of midas you use (e.g. the output of git describe --tags in $MIDASSYS), which operating system, what you did, and what happened. Include any errors from the message log.

Sharing your code

Code that you wrote for your own hardware, such as drivers and frontends for digitizers or power supplies, can help other experiments get started. See Community contributions for the packages that are already available, and how to add yours.

Contributing changes to midas

The source code is in the midas repository on TRIUMF's GitLab. Changes are made on the develop branch.

You need an account on TRIUMF's GitLab to fork the repository and open merge requests. Accounts can only be created with an email address from an approved domain, such as @triumf.ca or @psi.ch. If you need write access to the midas repository itself, send a private message to the core developers rather than asking on the forum.

  1. Fork the repository on GitLab
  2. Make your changes on a branch of develop
  3. Build midas, and run the tests
  4. Open a merge request into develop

For a larger change, describe it on the forum before you start, so that the developers can tell you whether it fits with their plans.

Midas is licensed under the GNU General Public License, version 2.

Guidelines

Think about backward compatibility. Midas is used by many programs around the world, and experiments update midas without always changing their own code. Where you can, keep the behaviour of existing code, including its functions, the input it accepts and its side effects, and prefer adding new features to changing existing ones. Breaking changes are sometimes worth it, e.g. to remove old code that makes midas harder to maintain. If your change breaks compatibility, explain why in the merge request, and add it to the breaking changes and upgrade guide in the release notes.

Match the existing code style. Prefer compact, readable code, and match the style of the surrounding code. Add a short comment above each function whose purpose isn't clear from its name and arguments. Comment complicated code to explain what it is for, rather than repeating what it does.

Add tests. Ideally, you should add tests to the test suite for new features and bug fixes, and run it before you open a merge request. GitLab only runs the test suite on a schedule, not for each merge request. If you are struggling, contact Derek Fujimoto.

Contributing to the documentation

This documentation is in the midas repository, as Markdown files in doc/mkdocs/md. Ben Smith is responsible for it, and reviews the whole documentation before each release.

Small changes are welcome, e.g. fixing a mistake or adding a missing explanation. Change the files and open a merge request, as for code changes. Before you write a larger section or a new page, discuss it with Ben first. See Editing and building this documentation for how the documentation is organised and built.