Skip to content

Contributing guidelines

Welcome! Duqtools is an open-source project that aims to work with a wide range of IMAS data for fusion research. If you're trying duqtools with your data, your experience, questions, bugs you encountered, and suggestions for improvement are important to the success of the project.

We have a Code of Conduct, please follow it in all your interactions with the project.

Questions, feedback, bugs

Use the search function to see if someone else already ran accross the same issue. Feel free to open a new issue here to ask a question, suggest improvements/new features, or report any bugs that you ran into.

Submitting changes

Even better than a good bug report is a fix for the bug or the implementation of a new feature. We welcome any contributions that help improve the code.

When contributing to this repository, please first discuss the change you wish to make via an issue with the owners of this repository before making a change.

Contributions can come in the form of:

  • Bug fixes
  • New features
  • Improvement of existing code
  • Updates to the documentation
  • ... ?

We use the usual GitHub pull-request flow. For more info see GitHub's own documentation.

Typically this means:

  1. Forking the repository and/or make a new branch
  2. Making your changes
  3. Make sure that the tests pass and add your own
  4. Update the documentation is updated for new features
  5. Pushing the code back to Github
  6. Create a new Pull Request

One of the code owners will review your code and request changes if needed. Once your changes have been approved, your contributions will become part of duqtools. 🎉

Getting started with development

Setup

Duqtools targets Python 3.9 or newer and is compatible with python 3.10, which is the version available on eufus.

Clone the repository into the duqtools directory:

git clone https://github.com/duqtools/duqtools

Install using virtualenv:

cd duqtools
python3 -m venv env
source env/bin/activate
python3 -m pip install -e .[develop]

Alternatively, install using Conda:

cd duqtools
conda create -n duqtools python=3.10
conda activate duqtools
pip install -e .[develop]

Running tests

Duqtools uses pytest to run the tests. You can run the tests for yourself using:

pytest

To check coverage:

coverage run -m pytest
coverage report  # to output to terminal
coverage html    # to generate html report

Running IMAS tests

Tests that require IMAS make use of the containerized_runs repository.

You can run the tests following the instructions in the repo, or locally. Clone the repository and set the CONTAINERIZED_RUNS_DIR environment variable. For example, on Gateway:

cd $JRUNS
git clone git@github.com:duqtools/containerized_runs
export CONTAINERIZED_RUNS_DIR="$JRUNS/containerized_runs"

Building the documentation

The documentation is written in markdown, and uses mkdocs to generate the pages.

To build the documentation for yourself:

pip install -e .[docs]
mkdocs serve

You can find the documentation source in the docs directory. If you are adding new pages, make sure to update the listing in the mkdocs.yml under the nav entry.

Making a release

  1. Make a new release.

  2. Under 'Choose a tag', set the tag to the new version. The versioning scheme we use is SemVer, so bump the version (major/minor/patch) as needed. Bumping the version is handled transparently by bumpversion in this workflow.

  3. The upload to pypi is triggered when a release is published and handled by this workflow.

  4. The upload to zenodo is triggered when a release is published.