Contributing

First off, thank you for considering contributing to HEIMDALL. 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 to improve pyHeimdall or one of its connectors, or even xHeimdall. 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’re that kind of person.

Ground rules

What follows is a generic version of each project CONTRIBUTING.rst documents, available on each project’s source code repository. Check those out for the full, up-to-date advice:

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 relating to pyHeimdall, make sure to answer these five questions:

  1. What version of Python are you using (python --version)?

  2. Do you use the latest version of the software (pip install --upgrade .)?

  3. What did you do?

  4. What did you expect to see?

  5. What did you see instead?

Of course, when filling a new issue relating to xHeimdall, info about your XQuery/BaseX environment if more relevant.

Modifying the software

Changes are welcome via GitLab 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 roadmaps.

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 is compliant with the existing code style.

  • 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.

Feel free to ask for help. 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, costly and liberticide version of GitLab. The majority of what you’d read about GitHub in those pages applies to GitLab too.