Contributing

Introduction

First off, thank you for considering contributing to this project. Please take a moment to review this document in order to make the contribution process easy and effective for everyone involved.

Following these guidelines helps to communicate that you respect the time of the other contributors. In return, they’d reciprocate by trying to addressing your issue, assessing changes, or helping you however they are able to.

This is a free software and we love to receive contributions from our community — you! There are many ways to contribute, from writing tutorials or improving the documentation, to submitting bug reports and feature requests or writing code. No big commitment required; even if all you do is point out an anomaly, give your opinion or fix a typo, you are a contributor.

As for everything else in the project, the contributions are governed by our code of conduct of respect, collaboration, sobriety and overall non-bullshittery and non-dickheadness. Here is an example if you need one.

Asking questions, reporting bugs

Please, don’t send us emails for questions, bug reports or general social activities related to the project. For the sake of FAIRness and to not increase the workload of other contributors, all these should happen in public issues.

When filling a new issue, make sure to answer these questions, if applicable:

  1. What is your environment version(s)?

  2. Do you use the latest version of the software?

  3. What did you do?

  4. What did you expect to see?

  5. What did you see instead?

Modifying the software

Changes are welcome via merge requests. If you are new to the project and looking for a way to get involved, try picking up an issue with the “up-for-grabs” label. Hints about what needs to be done are usually provided.

Another good place for finding (or confirming an) inspiration is the project roadmap.

For all merge requests, please respect the following guidelines:

  • Each merge request should implement one feature or bugfix. If you want to add or fix more than one thing, submit more than one pull request.

  • Keep it simple and self-contained. Don’t add stuff to the codebase unless absolutely needed. For example, err on the side of using simple functions rather than huge classes. Modify only files that are irrelevant to your feature or bugfix.

  • Do not add dependencies to the project.

  • Ensure cross-version and cross-platform compatibility.

  • Ensure your code that goes is compliant with the relevant style guide.

  • Fully cover and specify your code with automated tests, and make sure you don’t “break” any existing test.

  • Don’t forget agree to the DCO in each commit. This can easily be done using the --signoff Git option.

Small contributions, where the content is small enough to not be considered intellectual property, can be submitted as a patch. We’re talking about obvious fixes that do not introduce any new functionality or creative thinking. Some likely examples include the following:

  • Spelling / grammar fixes, typo correction, white space and formatting changes

  • Comment clean up

  • Adding logging messages or debugging output

Feel free to ask for help using the issue system. Everyone was a beginner at first!

Follow-up and resource materials

The last 2 resources talk about GitHub which is, in the context of research software, just an overall inferior version of GitLab. The majority of what you’d read about GitHub in those pages applies to GitLab too.